Release Note for 
BiiN IM Operating System Manuals 



iTM 



This relase note consists of three parts: 
• General operating system information 



tTM, 



• The BUN I OS Guide part, and 

• The BiiN™IOS Reference Manual part (including new chapters to be added to the manual). 



General Operating System Information 

TM 

This release note provides release information for OS VI .01 .00 of the BiiN operating system. 
This OS release is compatible with: 

Table 1. System Software Set FCS1 R1.2 



Release 


Description 


SM V2.00.01 


System Monitor — Firmware on EEPROM. 


OSBASE VI. 01. 00 


Operating System and CLEX. 


OS UTIL VI. 01. 00 


Utilities 1. 


UX VI. 01. 00 


UNIX-Based Software and Utilities. 


UTILS VI. 01. 08 


Utilities 2. 


SPOOL VI. 01. 07 


Printer/Spooling Software. 


MDS VI. 00. 03 


Maintenance and Diagnostics Software. 


ADA VI. 00. 06 


Ada Compiler. 


C VI. 00. 06 


C Compiler. 


FORTRAN VI. 00. 07 


FORTRAN Compiler. 


COBOL VI. 00. 03 


COBOL Compiler. 


PASCAL VI. 00. 07 


Pascal Compiler. 


LINK VI. 01. 03 


Linker. 


LIBRARIAN VI. 01. 01 


Librarian. 


DEBUGGER V2.00.00 


Debugger. 


EMACS V2.00.06 


Emacs Text Editor. 


FORMS VI. 02. 06 


Form Service and Utilities. 


SMS V2.00.01 


Software Management System. 


FTS VI. 02. 11 


ISO File Transfer Software. 



Compiling and Linking Information 

This section provides some additional information about compiling and linking programs that 
use most OS packages. 

When compiling an Ada program that uses the OS, you must specify the location of the OS 
package interface files. You do this using a pathname of the form: 
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/lib/ module jtame/os library 



You can compile Ada programs that make use of OS service calls by attaching OS libraries to 
your local ada_libr ar y. The following two libraries are required: 

/lib/kernel/ada_library 
/lib/gcos/ada_library 
All the other OS libraries also reside in / lib modules. The modules contained in / lib are: 



ada rts/ 


ctm/ 


gsO hw 


nulldev/ 


bdisk/ 


dist_supp/ 


gsOhdlcline/ 


pipe/ 


bstreamer/ 


dod_echo_daemon/ 


gsOlandriver/ 


print inpmgt/ 


carrier_mgt/ 


dod tftp daemon/ 


has/ 


psmgt/ 


chouse/ 


dod transp mgt/ 


hdlc/ 


pss/ 


cluster_svr/ 


envrec/ 


hsappl/ 


set/ 


cms up/ 


ethernet/ 


ieee8023/ 


sms/ 


cmtest/ 


fe/ 


iso_echo_daemon/ 


sort_merge/ 


comm trace/ 


f ield_access/ 


iso transp__mgt/ 


ssm/ 


cp_async/ 


forms/ 


kernel/ 


stream_io/ 


cp_mgt/ 


fts/ 


linkcall/ 


term__inpmgt/ 


cp_scsi/ 


gcos/ 


nodeconf ig/ 


terminfo/ 




qdp diaq/ 




ux/ 



Each of these modules contains some or all of the following OS libraries: 
views - A directory containing the views for the service, named 



view. 



image - The binary object image of the package. 

vtables - A directory containing one vtable file per view per 
domain. A vtable file defines the procedure entry 
points to be included in a view. 

viewdir s - A directory containing one view directive file for 
each view supplied by the service. 

ada_library - An optimized Ada library that provides the 
Ada interfaces to the service. 

include - A linker library containing the C header files needed 
to compile and link a C program that uses C system 
bindings to call OS function calls. 

sre - package specification source files 

lib - alias for ada library/ lib 



kernel has one additional library, clib, a C library. 

General Caveats 

This section lists major OS features that are not yet implemented: 

1. OS services are not distributed. 

2. Subtransactions are not supported. Attempting to start a subtransaction raises 

System_Exceptions . ©peration_not_supported. 
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3. The clustered and hashed file organizations are not supported. Hashed indexes are not 
supported. 

4. The OS does not support fault tolerant hardware, that is, hardware configured for fault 
checking or continuous operation. 

5. The report service is not implemented. 

6. IPI disks are not supported. 

7. Basic tape devices are not supported (although basic streamer devices are supported). 
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BUN /OS Guide Release Information 

This manual is about 65% complete. It does not describe: 
The clearinghouse 

Volume set management 

Basic disks, streamers, or tapes 

Guidelines for writing utilities 

Using time or timed requests 

Resource control or accounting 

Several types of advanced type managers 

Adding device drivers. 



Throughout 



Throughout 



H-3 



IV-4 



Several reviewers remarked that excerpts from examples don't always 
show enough context. If an excerpt is confusing, check the complete ex- 
ample listing in Appendix A. We will be expanding our excerpts in many 
cases in subsequent releases. 

Some of the examples are tested. All of them have been compiled, though 
with an earlier version of the Ada compiler than the version in this system 
release. 

If an operation begins to store a master AD for an object, but fails, then no 
master AD can ever be stored for the object. One way this can happen is to 
store the master within a transaction and then abort the transaction. Abort- 
ing the transaction does undo the storing of the AD, but still no master AD 
can ever again be stored for the object A particular case to avoid is: 

begin 

Directory_Mgt . Store (somejiame, x) ; 
exception 

when Directory_Mgt .entry_exists => 
Directory_Mgt. Delete (somejiame) ; 
Directory_Mgt . Store (somejiame, x) ; 
end; 
Passive_Store_Mgt. Update (x) ; 

This code will not work! The first Store tries to store the master AD and 
fails; the subsequent store works but stores only an alias. The Update 
call will raise Passive_Store_Mgt . no_master_AD. Such a code 
fragment can be rewritten as follows: 

begin 

Directory_Mgt . Delete (somejiame) ; 
exception 

when Directory_Mgt ,no_access => 
null; 

— There was nothing to delete, 
end; 

Directory_Mgt . Store {somejiame, x) ; 
Passive_Store_Mgt . Update (x) ; 

Several of the illustrations show window shapes that are only possible on 
graphic terminals. Windows on character terminals are always as wide as 
the screen and are tiled, not overlapping. 
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IV-4-10 Figure IV-4-5 is incorrect. 

IV-4- 15 Character display I/O can be used via an opened window even if the win- 

dow was opened with another access method. 

IV-6K This Printing chapter now has updated examples from a new version of 

Print_cmd_ex (included in this release note beginning on the next 
page). Specific changes are: 

• An application must specify Device_Def s . nothing for the 
allow parameter on an Open call. 

• Ensure that the requested sheet size is within the printer's capability. 

IV-7-6 A slot in a relative file is not removed if the record it contains is deleted. 

VI-1-16 Table VI-1-2 should also list the resource_exhausted local event. 

By default it is enabled. The default handler kills the process. 

VI-3-3 Figure VI-3-1 is incorrect. There are no processes in queues greater than 

priority 15. 
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Print_cmd_ex Example Procedure 

1 with 

1 2 Byte_Stream_AM, 

3 CL_Defs, 

4 Command_Handler, 

5 Device_Defs, 

6 Directory_Mgt, 

7 Incident_Defs, 

8 Message_Services, 

9 Process_Mgt, 

10 Process_Mgt_Types, 

11 Spool_Defs, 

12 Spool_Device_Mgt, 

13 . String_List_Mgt f 

14 System, 

15 System_Defs, 

16 Text_Mgt; 

17 • 

18 procedure Print_cmd_ex is 
19 

20 — Function: 

I 21 — Defines a command to print from a file or other 

22 — byte stream source 
23 

24 — History: 

25 — 12-??-87, E. Sassone: Initial Version 

26 — 06-30-88, E. Sassone: Working Version 
27 

28 — Command Definition: 

29 — The command has the form: 
30 

31 — print 

32 — [source=<pathname>] 

33 — [on=<pathname>] 
! 34 

35 — The on argument can either be a spool queue or a 

36 — printer (for direct printing) . The default is a 

37 — system standard spooling device. The source 

38 — argument will default to standard input. 
39 

40 — *D* manage. commands 

41 — *D* create. in vocation_command 

42 — *D* 

43 — *D* define. argument source :type = string 

44 — *D* set .lexical_class symbolic_name 

45 — *D* set .maximum_length 80 
4 6 — *D* set.value_default ,,,, 
47 — *D* end 

) 48 — *D* 

49 — *d* define. argument on :type = string 

50 — *D* set .lexical_class symbolic_name 

51 — *D* set .maximum_length 80 

52 — *D* set.value_default "" 

53 — *D* end 

54 — *D* end 

55 — *D* exit 
56 

57 

58 use System; 

59 

60 msg_ob j : constant System. untyped_word := System. null_word; 

61 

62 no_print_device_code: 

63 constant Incident_Def s. incident_code := ( 

64 module => 0, 

65 number => 1, 

66 severity => Incident_Defs. error, 
\ 67 message_object => msg_obj); 



68 
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69 units_not_supported_code: 

70 constant Incident_Defs. incident_code := ( 

71 module => 0, 

72 number => 2, 

73 severity => Incident_Defs .error, 

74 message_object => msg_obj); 
75 

7 6 

77 — *D* manage. messages 
78 

79 no_print_device: exception; 

80 — *D* store :module=0 :number=l \ 

81 — *D* :msg_name=name_space_created_code \ 

82 — *d* : short = \ 

83 — *D* "Print Device $pl<on> does not exist." 
84 

85 

86 — *D* store :module=0 :number=2 \ 

87 — *D* :msg_name=units_not_supported_code \ 

88 — *D* : short = \ 

8 9 — *D* "Unit $pl<on> not supported." 
90 

91 opened_cmd: Device_Def s.opened_device; 

92 — Opened command input device. 
93 

94 source: System_Def s. text (80) := (80, 0, (others => ' ')); 

95 — Pathname of file or device to print from 
96 

97 open_source: Device_Def s. opened_device; 

98 — opened source file or input device 
99 

100 on_device: System_Def s. text (Incident_Defs .txt_length) := 

101 (Incident_Defs.txt_length, 0, (others => ' ')); 

102 ' — Pathname of spool queue or printer 
103 

104 spool_queue: Device_Defs. device; 

105 

106 print_device: Device_Defs. device; 

107 

108 sheet_size: constant Spool_Def s.size_t := (80,60); 

109 — NOTE: Make sure this is within the capabilities 

110 — of your printer, otherwise the program will appear to 

111 — execute successfully but there will be no output. 
112 

113 open_print: Device_Def s.opened_device; 

114 — opened print_device 
115 

116 — buffer variables 

117 buffer_size: constant System. ordinal := 4_096; 

118 buffer: arrayd .. buffer_size) of 

119 System. byte_ordinal; 

120 bytes_read: System. ordinal; 
121 

122 begin 

123 

124 — Get command arguments: 

125 

126 opened_cmd := Command_Handler .Open_invocation_command_processing; 

127 CommandJHandler .Get_string( 

128 cmd_odo => opened_cmd, 

129 arg_n umber => 1, 

130 arg_value => source) ; 

131 Command_Handler . Get_string( 

132 cmd_odo => opened_cmd, 

133 arg_number => 2, 

134 arg_value => on_device); 

135 Command_Handler .Close (opened_cmd) ; 
136 

137 — uses terminal input if no file specified 

138 if source. length = then 
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139 open_source := 

140 Process_Mgt . Getj?rocess_globals_entry ( 

141 Process_Mgt_Types.standard_input) ; 

142 — standard input from terminal 

143 else 

144 open_source := Byte_Stream_AM.Open_by_name ( 
14 5 name => source, 

146 input_output => Device_Defs . input) ; 

147 end if; 
148 

14 9 — use default queue if not specified 

150 if on_device. length = then 

151 Text_Mgt . Set (on_device, "/sys/spool_q") ; 

152 — Current name of default system spool queue 

153 end if; 
154 

155 — check the "on_device" for spooled or direct 

156 — printing, else error 

157 spool_queue := Directory_Mgt .Retrieve (on_device) ; 
158 

159 if Spool_Defs . Is_spool_queue (spool_queue) then 

160 — spool file 

161 print_device := 

162 Spool_Device_Mgt . Cr eate_pr int_device ( 

163 spool_queue => spool_queue, 

164 pixel_units => false, 

165 print_area => sheet_size) ; 
166 

167 elsif Spool_Defs. Is_print_device (spool_queue) then 

168 — direct printing 

169 print_device := 

170 Spool_Device_Mgt . Create_print_device ( 

171 spool_queue => spool_queue, 

172 pixel_units => false, 

173 print_area => sheet_size, 

174 print_mode => Spool_Defs .page_wise) ; 
175 

176 else 

177 RAISE no_print_device; 

178 end if; 
179 

180 open_print := 

181 Byt e_Stream_AM. Ops. Open ( 

182 dev => print_device, 

183 input_output => Device_Defs .output, 

184 allow => Device_Def s. nothing) ; 
185 

186 — read file in 4K chunks 

187 while not Byte_Stream_AM.Ops .At_end_of_f ile (open_source) 

188 loop 

189 bytes_read := Byte_Stream_AM. Ops. Read ( 

190 opened_dev => open_source, 

191 buffer_VA => buffer 'address, 

192 length => buf fer_size) ; 
193 

194 Byte_Stream_AM.Ops.Write( 

195 opened_dev => open_print, 

196 buffer_VA => buffer 'address, 

197 length => bytes_read) ; 

198 end loop; 
199 

200 Byte_Stream_AM. Ops. Close (open_source) ; 

201 Byte_Stream_AM. Ops. Close (open_j?rint) ; 
202 

203 exception 
204 

205 when no_print_device => 

206 Message_Services.Write_msg( 

207 msg_id => no_print_device_code, 

208 paraml => Incident Defs. message parameter' { 
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209 typ => Incident_Defs.txt, 

210 len => on_device.max_length, 

211 txt_val => on_device) ) ; 
212 

213 when Spool_Device_Mgt .units_not_supported => 

214 Message_Services .Write_msg { 

215 msg_id => units_not_supported_code, 

216 paraml => Incident_Def s.message_parameter' < 

217 typ => Incident_Defs.txt, 

218 len => on_device .max_length, 

219 txt_val => on_device) ) ; 
220 

221 when Device_Def s .end_of_f ile => 

222 Byte_Stream_AM. Ops. Close (open_source) ; 

223 Byte_St ream_AM. Ops. Close (open_print) ; 
224 

225 end Print_cmd_ex; 
226 
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BiiN™/OS Reference Manual Release Information 

This section describes detailed problems or limitations within this OS release. Workarounds 
are provided for some problems. 

This section is organized by service area, service and Ada package. See Chapter 2 for a 
description of services and service areas. Only those service areas, services and packages that 
have caveats are listed. 

Support Services 

Message Service 

See the Release Note for BiiN™ Command and Message Guide. 

Object Service 

1. Pas sive_Store_Mgt . Copy is not supported for directories. One effect of this limita- 
tion is that if you copy or move an executable program that is connected to command 
definitions, the connection is lost and must be reestablished. This is because the program's 
Outside Environment Object (OEO) is a standalone directory. 

2. Passive_Store_Mgt . Set_home_job is not supported. Therefore, local single- 
activation type managers are not supported. 

3. Pas sive_Store_Mgt . Copy started within a transaction doesn't return claimed disk 
space if Abort was sent from another job. 

This is unlikely to occur in most programming applications since the transaction and the 
copy occur in the same job. In some applications, a user may surround a copy with the 
CLEX commands start . transaction and abort . transaction. In this case, the 
transaction is started and aborted in the CLEX job while any file copies are performed by 

TM 

some other job. (Both the BiiN /UX cp command and the CLEX copy . ob ject utility 
use Passive_Store_Mgt . Copy. 

Passive_Store_Mgt . Update_with_alternate_rep does not work if invoked 
with a page alternate rep that contains one or more data-only pages. If this situation occurs, 
an appropriate message is pushed on the caller's message stack and 
"System_Exceptions.system_intemal_error" is raised. No damage has been done and the 
system will continue to function normally. 

Directory Services 

Naming Service 

1. A pathname, when expanded to a full pathname, cannot exceed 256 bytes. 

2. Directories do not support logging. The perf orm_logging parameters to 
DirectoryJMgt . Create_directory and 
Standalone_Directory_Mgt . Create_directory are ignored. 

3. Dir ectory_Mgt . Get_name does not read-lock any part of the resulting full pathname. 

4. Directories (normal, active, or standalone) do not support the 
Passive_Store_Mgt . Copy call. Programs or scripts which have GCOS command 
files cannot be copied since the command file is stored in the Outside Environment Object 
which is a standalone directory. The program or script itself is copied, but 

manage . commands must be rerun on the program in the new location. 
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5. Customized_Name_Mgt . Ops and Direct or y_Mgt Rename and Delete opera- 
tions on master entries may fail due to a timestamp conflict if the object in question has 
another alias on the same volume set and this alias is locked by a more recent transaction. 
In this case, the transaction enclosing the rename or delete needs to be aborted and the 
operation should be retried. 

6. ID protection sets are currently limited to ten entries. This limits the number of users in a 
single group. 

I/O Services 

Basic I/O Service 

1. Byte stream I/O to record-structured files is not supported. 

2. Record I/O to stream files is not supported. 

Character Terminal Service 

1. A character window cannot be opened by more than 64 jobs. 

2. Character terminal windows do not support record I/O. 

3. The Character_Display_AM . Ops . Ring_bell call only supports audible alarms, 
regardless of the audible parameter's value. If the underlying device cannot produce an 
audible alarm, then Ring_bell does nothing. 

4. The Terminal_Def s . window_attr . track_cur sor window output control field 
is not supported. Even if this field is set to true, the view will not track the cursor. 

5. The Terminal_Inf o .Process_param_string call does not support 
%code if-then-else . 

Print Service and Spool Service 

1. The Print info package, used to describe new printers, is not yet supported. 

2. The print service does not provide any information about a printer's physical status (for 
example, offline, not ready, no paper). The user must check the printer for such problems. 

3. Spooled data can be lost if a printer is switched off or disconnected during printing. 

4. Removing a spool queue, other than with remove . spool_queue or 
Spool_Device_Mgt . Delete_device, will crash the spooling daemon requiring 
reinstallation of the spool service. 

5. Invoke the stop . ps s utility to safely shutdown spooling before rebooting the system. If 
the system is locked up so that this cannot be done, then rebooting crashes spooling, requir- 
ing reinstallation of the spool service. PSS may be crashed by a system cold start without 
previous shutdown. (The shutdown script includes stopping PSS.) 

6. If a small amount of data Oess than IK bytes) is spooled into an empty spool queue, then 
the spool file immediately disappears from the queue, even though it is not printed or may 
not be printed at all (for example, due to an offline printer). 

7. Print and Spool Services can service several spool queues each of which can only be con- 
nected to a single printer. 
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Print Priority Evaluation of Several Spool Queues: 

If you have created several spool queues equipped with the same print priority be aware of this 
Spool Service behavior: 

Current documentation states that in such a case, spool queues of the same priority are spooled 
out in the following manner: 

first file from first queue, 
first file from second queue, ..., 
first file from n-th queue, 
second file from first queue, 
second file from second queue, ..., 
second file from n-th queue, 
third file from first queue, etc. 

But Spool Service now spools out in the following manner: 

first file from first queue, 
second file from first queue, ..., 
n-th file from first queue, 
first file from second queue, 
second file from second queue, ..., 
m-th file from second queue, etc. 

Spool Queue Print Delay: 

Spool Service internally defines an interval of four hours during which spooling out requests 
are directed against spool files ready for printing. 

Accordingly, a spool queue being equipped with a print delay of class time behaves as follows: 

Beginning with the time of the day specified for the print time, Spool Service spools out all 
spool files ready for printing during four hours. After print time plus four hours, no new 
spooled in data are printed. 

This also holds for a spool queue with a print delay of class size: If data are spooled in before 
the print time specified is reached, only those spool files smaller than the size limit are im- 
mediately printed. Four hours after the beginning of the print time, all spool files ready for 
printing are spooled out. After print time plus four hours, only those spool files smaller than 
the size limit are submitted to a printer. 

Volume Space Exhaustion: 

If during spooling the exception volume_space_exhausted is raised, the spool queue affected 
cannot be removed. The OS raises this exception even if the AD to the spool queue affected is 
simply retrieved. System Administrators should ensure that the volume set on which a spool 
queue is installed has enough blocks free for the spool files to be created. 

Printer Error Handling: 

In case of errors on the PT89 printer such as power failure, low paper, out of ink, or discon- 
necting of the cable, switch the printer off-line and on-line again This causes the device driver 
to receive an XON character. 

Printer Configuration Support: 
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Currently Printer Management does not support the Detach and Stop operations of the 
configuration attribute. So to deconfigure one or more printers, modify the System/User SCO 
and then perform a warmstart. 

Native Mode Printing: 

Applications doing native mode printing (spooled or directly) are constrained by the following 
limitations: 

• Although on an "Open", Spool Service checks the print area size and position against the 
size of the currently mounted paper (exception device_i nope rat ive), it is still pos- 
sible to write on the cylinder in native mode. 

• Linewrap and scroll and all other page output attributes are not evaluated in native mode. 

• If a native mode printing application sets top of form (via an escape sequence), the printer 
device manager has no chance of resetting the correct top of form. 

If you print characters in native mode, they get printed on the paper only if a FF or a LF or a 
CR is issued. This is a common printer property (although often not documented). 

Authority List Protection of Spool Service Objects: 

Spool Service supports authority list protection of the different Spool Service objects. The 
material presented in this section are more usage suggestions than caveats. 

The application (utility) creating a spool queue should take into account that Spool Service 
protects the spool queue by the authority list found in the process globals of the application 
(utility) invoking the Install function of the Spool_Queue_Admin package. Accord- 
ingly, the spool queue creator should have registered all users wanting to make use of that 
spool queue with modify rights (for direct or spooled writing) and use rights (for inquiries) in 
the authority list of his process globals: 



• 



• 






Create an authority list via the manage . authority utility granting use and modify 
rights to all potential users of the spool queue. 

Register the authority list created in your process globals by the command 

set. variable pglob. author it y_list <new_authority_list> 
: global. 

Alternatively, modify the spool queue's protecting authority list after you have created the 
spool queue. On spool queue installation, Spool Service creates a standalone directory 
within which you'll find an entry named . < spool_queue_basename>_AL. If you 
modify this authority list (e.g. by granting "world" for "um" access), the user(s) to register 
in this list with use and/or modify rights are allowed to deal with that spool queue. But 
beware that you do not remove "system" (or any of system's rights) from that authority list. 

Spool Service registers the process doing the install as "Spool Queue Administrator". The 
Spool Queue Administrator itself should make sure to have modify rights and use rights on 
the printers) to be connected with the spool queue. 

When a user having use rights on the spool queue calls 
Spool_Queue_Admin . Get_rank_list, he gets ADs with use rights of all spool 
files ranked. If Spool Service determines the caller to be either the Spool Queue Ad- 
ministrator or the owner of the spool file, that is, the application having created the spool 
file on an Open of a spooled print device, the corresponding spool file AD(s) additionally 
will get modify rights. According to the type rights necessary to delete a spool file the 
owner of the spool file or the Spool Queue Administrator can remove a spool file from the 
spool queue rank. 
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Interrelation of BiiN™/UX and Spool Service: 

During the installation of Spool Service, install, pss activates a (revised) User SCO. 
Within the appropriate SCO description file there is a line that leads to the start of BiiN /UX. 
Whether or not Spool Service successfully is booted in case that line is omitted is undeter- 
mined. 

Spool Service Installation and User Access: 

The user (ID and authority list) installing Spool Service by invoking install, pss 
represents "Spool Service*'. The user installing Spool Service must be granted access to create 
entries in the /msg, /sys [ /lib], and /tdo directories. Hence, it is strongly recommend 
that Spool Service be installed as system. 

The system user should never remove the Spool Service configuration object stored under 
/sys /spool, otherwise Spool Service won't be usable. The same applies if the Spool Ser- 
vice ID (system) and/or all access rights are removed from public objects such as spool 
queue, printer, message file). 

Print and Spool Service Interfaces: Following is a list of the Print and Spool Services 
external interfaces and AM support with comments on the current support. 

Package Spool_Def s: 

Due to missing support for printinfo and printer emulation, Is_emulat ion and 
Is_printinf o always return false. 

Package Spool_Device_Mgt: 

Get_spool_device_attr_ID returns a retyped instance of 

Extra_Attributes . attribute_l. 

Package Spool_Queue_Admin: 

Due to the lack printinfo support, Install does not evaluate a printinfo reference and 
Get_printinf o returns a System. null_word. 

Package Printer_Admin: 

Set_pr inter_type accepts only 'G' for a GENICOM printer or a *P* for a PT89 printer. 

Access Method Support for Spooled and Direct Printing: 

Previous documentation stated that during spooling data into a spool file, Print and Spool 
Services destroy the spool file and close the print device when the exception 
File_Def s . volume_space_exhausted is raised. This functionality is not fully sup- 
ported, that is, only the exception is propagated but the spool file is not destroyed nor is the 
print device closed. 

The Character Display AM is not supported for native mode print devices in any print mode. 

Char act er_Display_AM . Ops . Set_enhancement and 

Char act er_Display_AM . Ops . Set_region_enhancement are no-ops in both print 

modes supported. 
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Filing Service 

1 . For structured files, the unordered file organization is Recommended. 

2. Disk space allocated to open temporary files is lost if the system crashes. Disk space 
allocated to open stream files may also be lost if the system crashes. 

3. An unnamed file created within a transaction cannot be removed if the transaction times 
out. 

4. Files cannot contain records longer than 4,000 bytes for unordered or relative files, nor 
records longer than 60,000 bytes for sequential files. 

5. File buckets must be 4K bytes. The bytes_per_bucket field in the logical file 
descriptor, supplied when creating a file, is ignored. 

6. Long-term file logging is not supported. The 

File_Admin . logical_f ile_descr . long_term_logging field is ignored. 

7. File audit trails are not supported. The audit_trail_f ile parameter to 

File_Admin . Create_f ile is ignored. 

8. If an opened structured file is destroved in a transaction and the system crashes before the 
transaction is resolved, then broken file structures can result. To avoid this problem, don't 
use Directory_Mgt . Delete or Passive_Store_Mgt . Destroy to destroy struc- 
tured files within transactions. Instead, use a Destroy_f ile call. 

9. Index keys cannot contain long real fields. For string fields, the t_block type or the 
t_str ing type with or without the pi_varying property can be used. However, the 
t_str ing type with the pi_header property cannot be used. These types and 
properties are defined in the Data_Def inition_Mgt package. 

10. If a Passive_Store_Mgt . Copy operation on a file fails, then disk space allocated for 
the target file may not be reclaimed. Two cases in which disk space is not reclaimed are: 

• The destination volume set becomes full during the copy operation. 

• The copy operation is aborted because an enclosing transaction is aborted, and the job 
that aborts the transaction is not the same job that started the transaction. Specifically, 
avoid starting a transaction from the command line with start . transaction and 
then doing a copy operation within that transaction. 

1 1. Records cannot contain multivalued fields. 

12. There are three ways to insert records into a relative file: last (insert at EOF), first (use first 
available slot on the free list), and by a specific record number (by first using 

Set_ position to select a record slot). The "first" and "specific record number" tech- 
niques cannot both be used with the same file. Mixing these two techniques will have 
undefined results. 

13. The Field__Access package does not support conversion between base types. 

14. Field_Access does not support initializing fields with default values. 

15. Field_Access does not check constraints. 

16. These File_Admin calls are not supported: 

Assign_new_audit_trail_f ile 
Deactivate_index 
Get_file_status 
Reorganize_f ile 
Reorganize index 
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17. The File_Admin . Build_index call requires its file parameter to be an empty and 
nonopen file. In other words, an application should build all indexes immediately after 
creating a file and before inserting any records into it. 

18. The File_Admin . Copy_f ile call write-locks (exclusively locks) both the source and 
target files. Copy_f ile also ignores its shrink and contiguous boolean parameters, 
behaving as if both are false. 

19. File_Admin . Empty_f ile cannot be called within a transaction. A workaround is to 
pop the transaction stack just before calling Empty_f ile and then push the popped trans- 
actions back onto the stack after the call. 

20. File_Admin . Get_index_status does not report num_f ree_buckets. 

21. Positioning of blocks in the reverse direction has not been fully tested for the 
Join_Interf ace package. 

22. Record_AM . Ops . Insert_control_record does not raise 
Device_Def s . length_error when the record length is less than the minimum 
length or greater than the maximum length. 

23. Record_AM . Ops . Unlock does not raise an exception if it is called for a non-existent 
record. 

24. A second Record_AM . Ops . Read call to read the current record after a successful 
Set_position call raises Record_AM.invalid_record_address, if the file 
was created with xm_locking true. 

25. After a Record_AM . Ops . Set^position call with an invalid record ID, a 
Recor d_AM . Ops . Read call to read the current record fails with an unspecified excep- 
tion. 

26. The Sort_Merge_Interf ace . Special_collation_sort_merge call only 
supports the t_block type defined by Data_Def initionJMgt. 

27. Recor d_AM . Truncate only operates in the default mode: EOF is the beginning of the 
file and all records are removed. (File_Admin . Empty_f ile performs the same 
function.) 

Data Definition Service 

1. Data_Def initionJMgt does not support binding of message names to message iden- 
tifiers. 

2. Dat a_Def inition_Mgt does not support binding of subprogram names to subprogram 
references. 

Volume Set Service 

1. Dismounting a volume set can cause a delayed system crash in some cases. Typically, the 
crash is caused b ecause Memory Management tries to page in a page of a partially- 
activated object that resides on the dismounted volume set. Since the page-in fails, 
Memory Management crashes the system. No data is corrupted and the system will operate 
normally when it is rebooted. 

2. The system needs to be rebooted after one or more volume sets have been restored from 
backup tapes. If this is not done, some information on the newly restored volume sets may 
not be accessible. 

3. Don't use the system volume set for application files and objects. Filling the system 
volume set and then crashing causes rebooting to fail, requiring a complete system rebuild. 
Another good reason to do all work on other volume sets is that it is impossible to backup 
the system volume set and later restore it. 
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4. Volume space allocated to temporary files is not reclaimed after a system crash and restart. 
Because of this, even the system administrator should avoid routinely logging in as 
system, because temporary files associated with CLEX will then be created on the system 
volume set, causing space to be lost if the system crashes and is restarted. 

5. A volume cannot contain more than 128M bytes. 

6. These Volume_Set_Admin calls are not supported: 

Copy_volume_set 
Empt y_vo lume_s e t 
Expand_volume_set 
Mo ve_vo 1 ume_s e t 

7. The VSM_D i s k_Admi n . Re name_di s k call is not available. 

Human Interface Services 

Command Service 

See the Release Note for Gemini Command Language Executive Guide and the Release Note 

jur Kjcrmru \sUUUIuaiua urui ivics&ugc Kjutuc. 

Form Service 

See the Release Note for Form Services. 

Program Services 

Concurrent Programming Service 

1 . Since the system administrator cannot limit the number of concurrent jobs, a large number 
of jobs may consume all of virtual memory and the system may lock up. The OS code that 
is invoked to kill a job may be on disk and unable to be swapped in. The system must be 
rebooted. 

2. The interactive attribute for pipes that are used in communications between EMACS and 
programs executing in shell windows is now supported. An additional boolean parameter, 
is_inter active has been added to Pipe_Mgt . Create_pipe. When set to true, 
the new pipe is interactive. 

function Create_pipe ( 

max_size: System. ordinal := 0; 

DDef: Data_Definition_Mgt .node_reference := ^ 

Data_Definition_Mgt .null_node_reference; 
is_interactive: boolean := false) 
return pipe_AD; 

Program Building Service 

1. It is possible to delete a program while it is executing but doing so may result in unpre- 
dictable behavior. 



Type Manager Services 

Configuration Service 



1. OS type managers that support the configuration attribute often have incomplete implemen- 
tations of that attribute. Many type managers don't fully support these 

Configuration. Ops calls: \, 
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Detach 

Get_creation_parameters 

Modify 

Scan 

Stop 

Transport Service 

1. The Virtual_Circuit_AM package does not support expedited data or negotiated con- 
nection establishment. 

Device Services 

Device Driver Service 

1. The OS does not support DPI disk drives. 

2. The OS driver for basic streamers does not retension the streamer tape. See the 
manage . tape utility description for information on how to retension the tape. 

Hardware Interface Services 

Hardware Service 

1 . Error reports logged in the SCT error log are not time-stamped. 

2. PS_Mgt . Retrieve__raw_PS can be used to retrieve an uninterpreted image of the data 
in the EEPROM. All other calls in P S_Mgt are not supported. 

3. SCT_Acces s . Get_hw_inf o returns a or incorrect value for the starting address of 
noninterleaved memory. 

4. Test_Support.Test_BXU only supports these subtests: error_report, FRC and 
parity. 

5. Test_Support . Test_CP is not supported. 

6. Test_Support . Test_memory_cont roller only uses Test_BXU to test the 
BXUs on BXU-based memory boards. 

BiiN™/OS Reference Manual Caveats 

This section lists documentation caveats for the BiiN^/OS Reference Manual. This manual is 
about 85% complete. Packages are listed in alphabetical order. 

Character_Display_AM 

Additional information about menus for character terminal windows includes: 

• Up to sixteen menu groups can be associated with a window. 

• A menu group can contain up to sixteen menus. However, the sums of the lengths of the 
menu titles plus five characters for each menu cannot exceed 80 characters. This ensures 
that the title bar can fit on one line. 

• A menu group title bar is displayed in the first row of the terminal screen if the active 
window has an enabled menu group. The menu group title bar contains the title of each 
menu plus a letter that can be used to select the menu. 

• The maximum number of menu items per menu is either 2 1 or the number of screen rows 
minus three, whichever is smaller. 
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• Menu item text length cannot exceed 65 characters. 

Command_Handler 

The Trigger_reclamat ion call requires a local AD with read and write rep rights for the 
countable object. 

Command_Handler . Get_line raises CL_Def s . illegal_syntax (symbol not 
complete) rather than Device_Def s . end_of_f ile if a A D is entered from the terminal. 



File Admin 



A minor violation of Level 3 consistency is possible: if a process attempts to read a record that 
does not exist, and if the record is then inserted by a concurrent process, and then the first 
process attempts its read again, the inserted record is visible. This feature of Level 3 consis- 
tency occurs because the "slot" or "ID" of a nonexistent record is not locked if such a read is 
attempted. 

File_Admin . Save_unnamed_f ile can raise 

~ _--.7 - _- ■ -..—.-.jr— ~ - — . ~~~ ~ "—-© — •- — ~~ ~,, n *.,~.«,>,. 

File_Admin . Create_unnamed_f ile 
Transaction_Mgt . Start_transaction 
File_Admin . Save_unnamed_f ile 
Transact ion_Mgt .Abort_transaction 
Transaction_Mgt . Start_transaction 
File_Admin. Save_unnamed_f ile 

This happens because if an operation begins to store a master AD for an object but fails, then 
no master AD can ever be stored for the object. This happens if the master AD is first stored 
within a transaction that is aborted. 

Record_AM 

Many calls in this package can raise ODO_using_dif f erent_transaction, but this 
exception is not yet listed. There are some other errors in the lists of what exceptions can be 
raised. 

Lock_all cannot raise Device_Def s . device_in_use. 

The system-defined lock escalation counters are 124 locks for Insert and Read, and 248 for 
Update and Delete. 

Record_AM . Ops . Truncate cannot be used to truncate a sequential file beginning at a 
particular record ID. 

TM_Transaction_Mgt . Transaction_Resolution 

The Notes section for Commit transaction was truncated. This section should read: 
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A type manager should not release any locks or resources associated 
with a transaction until its Conimit_transaction procedure is 
called. 

During post-crash recovery, a type manager may be called to commit a 
transaction that it has no knowledge of. In such a case, 
Commit_transaction should return normally. 

The type manager must be able to commit any prepared transaction. 

This call should not raise any exceptions. 

Appendix A 

The last two steps in Section A.4 should be corrected to: 

1 . Make the appropriate directory one of the directories to be searched for include files by the 
eg command: 



2. clex-> 



set. variable cg.incldir ($cg. incldir /lib/kernel/include) \ 



CONTINUE CMD: 



: global 



3. Place this line in each C source file that uses the OS package: 

♦include <Access_mgt .h> 

Additional BiiN™/OS Reference Manual Documentation 

The following Hardware Interface Service and FTS packages are contained in Vl.01.00 BiiN™ 
Operating System but are not in the 7/88 BiiN™IOS Reference Manual: 

FT_Support 

FT_Te sting 

KMDS_Defs 

SCT_Access 

SSM_Access 

SSM_Defs 

Test_Support 

FTS_Admin 

FTS_Config_Defs 

FTSJTransfer 

Not all of the procedures and functions in the Hardware Interface Service packages function as 
intended. A table accompanies each of the packages affected. 

The BUN™ I OS Reference Manual chapters for these packages are attached to this release note. 
Please add them to your BiiN™ I OS Reference Manual. 

NOTE 

SSM_Def s and KMDS_Def s are only used by privileged (trusted) users. 
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FTJSupport 



Procedure/Function 



Implemented 



Set_MC_toggle yes 

Set_FRC_split yes 
Set_transient_waiting_period no 

Attach_bus no 

Detach_bus no 

Marry_processor_module no 

Divorce_j?rocessor_module no 



Comments 



none . 
none . 
none . 
none . 
none . 
none . 
none . 



FTJTesting 



Procedure/Function 

Enable_FRC_testing 
Test_parity_and_BERL 

Test error_report 



Implemented 

yes 
yes 

yes 



Comments 



none. 

Due to BXU bug, this may 
cause a system crash. 
Due to BXU bug, this may 
cause a system crash. 



pot a ********* 



Procedure/Function 



Implemented 



Comments 



Retrieve_software_entry yes 
Set_system_monitor_parameters yes 
Retrieve_cardcage_entries yes 
Retrieve_device_entry yes 
Get_hardware_info yes 



Get_error_log 
Reserve_hw_entries 
Release hw entries 



yes 
yes 
yes 



none. 

none . 

none. 

none. 

Value of non-interleaved 

memory is wrong. 

Errors are not time stamped, 

none . 

none. 



SSM Access 



Procedure/Function 

Echo 

Read_re vision 

Read_UID 

Read_TOD 

Read_SSM_Conf ig 

Write_LED 

DC_Control 

Blower_control 

Read_error_log 

Read_SSM_inputs 

Send to MD 



Implemented 


Cor 


runent 


;s 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 


yes 


Single 


SSM 


only. 



<=© ^"P5€sO.O€b A*?®© 
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Test_Support 



Procedure /Function 

Test_GDP 

Test_CP 

Test_BXU 

Test_private_memory 

Test_memory_control ler 

Test_memory 

Set_board_LED 

Set_diagnostic_mode 

Set_normal_mode 

Map_prbcessor__ID_to_CP 



Implemented 


Comments 




yes 


none . 




no 


Null procedure. 




yes 


Only BCL tests from 
FT Testing supported. 




yes 


Only with system in 
diagnostic mode. 




yes 


BXU-based memory boards 


only 


yes 


BXU-based memory boards 


only 


yes 


none . 




yes 


none . 




yes 


none . 




yes 


none . 
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The following Hardware Interface Service and FTS packages are attached. Please add them to 
your BiiN™ I OS Reference Manual. 

FT_Support 

FT_Te sting 

KMDS_Defs 

SCT_Access 

SSM_Access 

SSM_Defs 

Test_Support 

FTS_Admin 

FTS_Config_Defs 

FTS Transfer 
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FT_Support 



Provides support for managing Fault Tolerant (FT) hardware functions. 

Security 



Calls 



Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



Attach_bus 

Sends an attach bus command to an AP-bus agent. 

Detach_bus 

Sends a detach bus command to the AP-bus agent. 

Divorce_processor_module 

Divorces a married processor and updates the SCT. 

Marry_processor_module 

Marries a shadow processor module to a primary processor module. 

Set_FRC_split 

Sets the FRC SPLITTING ENABLE bit in the FRC Splitting Control (FSC) 
register of the AP Bus agents. 

Set_MC_toggle 

Enables the TOGGLE MASTER CHECKER bit in the FRC register of the 
module's AP Bus agents. 

Set_transient_waiting_period 

Sets the MAXTIME register of every AP Bus agent in a cardcage. 



Summary 



Each procedure in this package performs a hardware FT function on one or more modules in a 
cardcage. FT_Support provides the first level of abstraction away from the hardware level 
for FT operations. These routines manipulate fault tolerant hardware. 

All of the procedures in this package automatically update the System Configuration Table 
(SCT) when necessary. 
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Exceptions 

not_FRCed 

The system cannot perform an operation because one of the target modules is not 
running as an FRC module. 

mo du 1 e_i s_QMRe d 

The system cannot perform an operation because one of the target modules is 
running as a QMR (married) modules. 

FT . Support . operation_f ailed 

The system cannot complete an operation. This condition usually indicates that 
one of the components in a target module will not respond to an Inter-agent Com- 
mand (IAQ. 

cannot_be_married 

The system cannot marry two modules. For example, a primary processor module 
that is running as the core module cannot marry a shadow processor module run- 
ning as a noncore module. 

one_bus_system 

Failed an attempt to perform a detach or attach bus operation in a single-bus 
system. A single-bus system only has one AP Bus per backplane. 
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Attach bus 



procedure Attach_bus ( 

bus: KMDS_Defs.one_bit_field; 

backplane: KMDS_Def s .cardcage_ID_rep := KMDS_Def s . sys) ; 
pragma out erf ace (VALUE, Attach_bus) ; 

Parameters 

bu s Bus to be attached. 

backplane Cardcage location of the bus. 

Operation 

Sends an attach bus command to an AP-bus agent. 

This procedure updates the System Configuration Table (SCT) and initiates an error report. 
The agent is specified by bus and backplane. 



Notes 



You can only use this procedure in 2-bus systems. 



Exceptions 

one_bus_system 
FT . Support . operation_f ailed 
SCT_Access . not_in_SCT 
SCT_Access . reserved_by_others 
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Detach bus 



procedure Detach_bus ( 

bus: KMDS_Defs.one_bit_field; 

backplane: KMDS_Def s .cardcage_ID_rep := KMDS_Def s . sys) ; 
pragma out erf ace (VALUE, Detach_bus) ; 

Parameters 

bu s Name of Bus to detach. 

backplane Location of bus (system or extension cardcage). 

Operation 

Sends a detach bus command to the AP-bus agent. 

The command deactivates the bus specified by bus and backplane. It updates the SCT and 
initiates an error report. 



Notes 



You can only use this procedure in a 2-bus system. 



Exceptions 

one_bus_system 
SCT_Access .not_in_SCT 
SCT_Access .reserved_by_others 
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Divorce_processor__module 



procedure Divorce_processor_module ( 

target : KMDS_Def s . logical_ID_rep) ; 
pragma outer face (VALUE, Divorce_processor_module) ; 

Parameters 

target ID of module to divorce. 

Operation 

Divorces a married processor and updates the SCT. 

Divorcing implies the separation of one AP-bus system from another or the splitting of a 
two-bus system into a one-bus system. 

Exceptions 

SCT_Access .not_in_SCT 
SCT_Access .reserved_by__others 
module not married 
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Marry _processor_module 



procedure Marry_processor_module ( 

primary_module: KMDS_Defs .logical_ID_rep; 

shadow_module: KMDS_Defs .logical_ID_rep) ; 
pragma out erf ace (VALUE, Marry_processor_module) ; 

Parameters 

pr imar y_mo du 1 e 

ID of designated primary module. 

shadow_module 

ID of designated shadow module. 

Operation 

Marries a shadow processor module to a primary processor module. 

Marriage implies the union of one AP-bus system to another or the creation of a two-bus 
system from two one-bus systems. After the marriage, this command enables the TOGGL1 
PRIMARY SHADOW bit and updates the SCT. 

Exceptions 

SCT_Access . not_in_SCT 
SCT_Access . reserved__by_others 
cannot be married 
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Set_FRC_split 



procedure Set_FRC_split ( 

target : KMDS_Def s . logical_ID_rep; 

backplane: KMDS_Def s.cardcage_ID_rep := KMDS_Def s .sys; 

enable: boolean := true); 
pragma outer face (VALUE, Set_FRC_split) ; 

Parameters 

target Logical ID of module to set master checker to toggle. 

backplane AP-Bus backplane target resident. 

enable If true, enable FRC splitting. If false, disable FRC splitting. 

Operation 

Sets the FRC SPLITTING ENABLE bit in the FRC Splitting Control (FSC) register of the AP 
Bus agents. 

target designates the module. 

Exceptions 

not_FRCed 
module_i s_QMRed 
SCT_Access . not_in_SCT 
SCT_Access .reserved_by_others 
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SetJMC_toggle 



procedure Set_MC_toggle ( 

target: KMDS_Def s. logical_ID_rep; 

backplane: KMDS_Def s . cardcage_ID_rep := KMDS_Def s . sys; 

enable: boolean := true); 
pragma out erf ace (VALUE, Set_MC_toggle) ; 

Parameters 

target Logical ID of module to set master checker to toggle. 

backplane AP-Bus backplane target resident. 

enable If true, enable MC toggle. If false, disable MC toggle. 

Operation 

Enables the TOGGLE MASTER CHECKER bit in the FRC register of the module's AP Bus 
agents. 

target designates the module. 

Exceptions 

mo du 1 e_i s_QMRe d 

not_FRCed 

SCT_Access . not_in_SCT 

SCT_Access. reserved by others 
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Set_transient__waiting_period 



procedure Set_transient_waiting_period ( 

max_time : KMDS_Def s . f our_bit_f ield; 

backplane: KMDS_Def s . cardcage_ID_rep := KMDS_Defs .sys) ; 
pragma outerf ace (VALUE, Set_transient_waiting_period) ; 

Parameters 

max_time Timing value for MAXTIME register, 

backplane Cardcage in which to change MAXTIME registers. 

Operation 

Sets the MAXTIME register of every AP Bus agent in a cardcage. 

The register is set to the value in max_t ime. This procedure does not write the MAXTIME 
TEST bit. As a result, this procedure does not allow you to test the MAXTIME counter. See 
the Biin Hardware Reference Manual for information about the MAXTIME counter. 

Exceptions 

FT . Support . operation_f ailed 
SCT Access. not in SCT 
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FT_Testing 



Provides operations used for latent fault testing. 

Security 

Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



Calls 



Enable_FRC_Testing 

Sets the TESTING ENABLE bit in the test detection register. 

Test_error_report 

Tests the priority circuits in the fault handling logic. 

Te st_par it y_and_BERL 

Tests the parity checking logic of the AP bus. 



Summary 



This package provides operations used for latent fault testing. Fault tolerant operations must 
be aware of which CPUs are operating as a shadow/primary or master/checker CPU. They 
must also know on which AP bus the boards are operating and must satisfy certain test con- 
ditions. 



Exceptions 



cannot_run_test 

Cannot set up to run test. 
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Declarations 



agentjocations 



type agent_locations is( 
shdw_checker_busO , 
shdw_checker_busl, 
shdw_master_busO, 
shdw_master_busl , 
prim_checker_busO, 
prim_checker_busl, 
prim_master_busO , 
prim_master_busl) ; 

for agent_locations use ( 

shdw_checker_busO => 2#00 0#, 

shdw_checker_busl => 2#001#, 

shdw_master_busO => 2#010#, 

shdw_master_busl => 2#011#, 

prim_checker_busO => 2#100#, 

prim_checker_busl => 2#101#, 

j-H. Aill UlGli3U<SJ, i_/UOU —*~ C IT J. J. V 1T f 

prim_master_busl => 2#111#); 

Lists all of the possible logical locations of an MCU or a BXU AP-Bus Agent in a logical 
module. The following list interprets the bit positions for this representation: 

bit Indicates the AP-bus component. 

bit 1 Indicates master or checker, = checker, 1 = master. 

bit 2 Indicates primary or shadow, = shadow, 1 = primary. 

Enumeration Literals: 

shdw_checker_busO 

Shadow Checker on AP-Bus 0. 

shdw_checker_busl 

Shadow Checker on AP-Bus 1. 

s h dw_ma s t e r_bu s 

Shadow Master on AP-Bus 0. 

s h dw_ma s t e r_bu s 1 

Shadow Master on AP-Bus 1. 

prim__checker_busO 

Primary Checker on AP-Bus 0. 

pr im_checker_bus 1 

Primary Checker on AP-Bus 1. 

pr imjna s t e r_bu s 

Primary Master on AP-Bus 0. 

prim_master_busl 

Primary Master on AP-Bus 1. 
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agent_test_list 



type agent_test_list is array (agent_locations) of boolean, 

Physical components within a logical module to test. 



test all 



test_all: constant agent_test_list := (others => true) 

Available AP-Bus agents to test. 



agent_test_results 



type agent_test_results is ( 
not_run, 
passed, 
no_response, 
failed) ; 

for agent_test_results' size use System. storage_unit; 

Possible test results for each physical component. 

Enumeration Literals: 

no t_r u n Test was not run on component. 

passed Component passed test. 

no_r e s po n s e Component did not respond to I AC which initiated test 

failed Component failed the test 



test results 



type test_results is array (agent_locations) of agent_test_results; 
pragma pack (test_results) ; 
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Enable__FRC_Testing 



procedure Enable_FRC_Testing { 

module_ID : KMDS_Def s . logical_ID_rep) ; 
pragma out erf ace (VALUE, Enable_FRC_Testing) ; 

Parameters 

mo du 1 e_l D Logical ID of module on which to enable testing. 

Operation 

Sets the TESTING ENABLE bit in the test detection register. 

The FRC circuits are self-checking whenever this bit is set. There is no need for any special 
test sequences to check their operation. Once enabled, the FRC circuits continue to check 
themselves until an error report turns off the TESTING ENABLE bit. Any error report turns 
off the TESTING ENABLE bit and disables FRC testing. See the BUN Hardware Reference 

Mnnnnl fr\r inform atirvn aKmnt th#» tpct fi^te^rtinn ne*ai<!tf*r 

Notes 

This procedure modifies the contents of the COM Register. The FRC circuits use the value in 
this register when they check themselves. See the system monitor information in the BUN 
System Administrator's Guide for COM register information. 

Exceptions 

KMDS_Def s .unresponsive_target 
FT_Support .operation failed 
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Test_error_report 



procedure Test_error_report ( 

module_ID : KMDS_Def s . logical_ID_rep; 

passed: out boolean; 

agent_re suits: out test_results; 

agent s_to_t est: agent_test_list := test_all); 
pragma out erf ace (VALUE, Test_error_report) ; 

Parameters 

mo du 1 e_l D Address of target AP-Bus agent(s) . 

passed If true, all agents passed test. 

agent_r e suit s 

Test results for each physical component. 

agent s_to_t est 

List of agents to be tested. 

Operation 

Tests the priority circuits in the fault handling logic. 

In addition, it corrupts the parity comparison in the long form error report receiver, which 
results in an Error Reporting error. It corrupts the comparison of the two messages sent within 
an error report, which also results in an Error Reporting error. See the BUN Diagnostic User's 
Guide for information about error reporting. The returned parameter is true if the test suc- 
ceeds, and false if the test fails. You can only use this test for testing BXUs and MCUs. 

Exceptions 

KMDS_Def s . unresponsive_target 
FT_Support .operation failed 
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Test_j3arity__.andJ3ERL 



procedure Test_parity_and_BERL ( 

module_ID : KMDS_Def s . logical_ID_rep; 

passed: out boolean; 

agent_results: out test_results; 

agents_to_test : agent_test_list := test_all); 
pragma out erf ace (VALUE, Test_parity_and_BERL) ; 

Parameters 

mo du 1 e_I D Address of target AP-Bus agent(s). 

passed If true, all agents passed test. 

agent_re suits 

Test results for each physical component. 

agent s_to_test 

List of agents to be tested. 

Operation 

Tests the parity checking logic of the AP bus. 

The package tests both parity trees of the parity checking logic of the AP bus. This operation 
also tests BXUs and MCUs. Since this test causes error reports, it also checks the functionality 
of the BERL. If the returned parameter is true, the test was successful; false if the test fails. 

Exceptions 

KMDS_Def s.unresponsive_target 
FT_Support .operation failed 
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KMDS Defs 



Contains basic definitions that the System Monitor, the Secondary Bootstrap Loader, and the 
Operating System need to operate. 



Security 



Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



Summary 



This package contains basic definitions used by the System Monitor, the Secondary Bootstrap 
Loader, and the Operating System. Changes to the types defined in this package may affect 
any or all of the systems listed above. 
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Declarations 



string_range 



subtype string_range is System. ordinal range 2 . . 255; 

In general, using Ada strings causes the compiler to allocate the data from heap (= object 
allocation), requiring system software support. Hence, the System Monitor has to define its 
own string type in order to make sure all allocations can be done on the stack. Note, the 
discriminant in fix_length_string is constrained, hence the compiler does not need to worry 
about worst case allocation (<>). 



fix_Iength_string 



type fix_length_string{ 
len: string_range) is 



j_ e^ui wi 



val: SCT_Types.char_array (1 
end record; 



len) 



fix_string_VA 



type f ix_string_VA is access f ix_length_string; 

pragma access_kind(f ix_string_VA, virtual); 

for f ix_length_string use 
record 

len at range . . 31; 

end record; 



fixj4_string 



subtype fix 4 string is fix length string (4) 



fix_8_string 



subtype fix 8 string is fix length string(8); 
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fix_16_string 



subtype f ix_16_string is f ix_length_string ( 16) 



fix_32_string 



subtype f ix_32_string is f ix_length_string (32) 



fix_64_string 



subtype f ix_64_string is f ix_length_string (64 ) 



one bit field 



subtype one_bit_field is System. ordinal range .. 16#1#, 

1 bit field. 



two bit field 



subtype two_bit_field is System. ordinal range .. 16#3#, 

2 bit field. 



three bit field 



subtype three_bit_field is System. ordinal range .. 16#7#, 

3 bit field. 



four bit field 



subtype four_bit_f ield is System. ordinal range . . 16#F#; 

4 bit field. 



KMDS Defs-3 



PRELIMINARY 



five bit field 



subtype five_bit_f ield is System. ordinal range . . 16#1F#, 

5 bit field. 



six bit field 



subtype six_bit_field is System. ordinal range .. 16#3F#; 

6 bit field. 



seven bit field 



subtype seven_bit_field is System. ordinal range .. 16#7F#; 

7 bit field. 



nine bit field 



subtype nine_bit_f ield is System. ordinal range . . 16#1FF#; 

9 bit field. 



ten bit field 



subtype ten_bit_f ield is System. ordinal range .. 16#3FF#, 



10 bit field. 



eleven bit field 



subtype eleven_bit_f ield is System. ordinal range . . 16#7FF#; 

11 bit field. 



twelve bit field 



subtype twelve_bit_f ield is System. ordinal range .. 16#FFF#; 

12 bit field. 
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thirteen bit field 



subtype thirteen_bit_f ield is System. ordinal range . . 16#1FFF#, 

13 bit field. 



fourteen bit Held 



subtype fourteen_bit_f ield is System. ordinal range . . 16#3FFF#, 

14 bit field. 



fifteen bit field 



subtype f ifteen_bit_f ield is System. ordinal range .. 16#7FFF4 

15 bit field. 



seventeen bit field 



subtype seventeen_bit_field is System. ordinal range .. 16#1FFFF#, 

17 bit field. 



eighteen_bit_field 



subtype eighteen_bit_f ield is System. ordinal range . . 16#3FFFF#; 

18 bit field. 



nineteen bit field 



subtype nineteen_bit_f ield is System. ordinal range .. 16#7FFFF#, 

19 bit field. 



twenty_bitjield 



subtype twenty_bit_field is System. ordinal range .. 16#FFFFF#; 

20 bit field. 



KMDS Defs-5 



PRELIMINARY 



twenty_one_bit_field 



subtype twenty_one_bit_f ield is System. ordinal range . . 16#1FFFFF#, 

21 bit field. 



twenty_two_bit_field 



subtype twenty_two_bit_f ield is System. ordinal range . . 16#3FFFFF#, 

22 bit field. 



twenty_four_bit_field 



subtype twenty_f our_bit_f ield is System. ordinal range .. 16#FFFFFF#, 

24 bit field. 



raw_4_bytes 



type raw_4_bytes is array ( 

System. ordinal range . . 3) of System. byte_ordinal; 

pragma pack (raw 4 bytes); 



raw_6Jbytes 



type raw_6_bytes is array ( 
System. ordinal range 

pragma pack(raw_6 bytes); 



5) of System. byte ordinal, 



raw_8_bytes 



type raw_8_bytes is array ( 
System. ordinal range 

pragma pack(raw_8_bytes) ; 



7) of System. byte ordinal; 
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raw_16_bytes 



type raw_16_bytes is array ( 

System. ordinal range . . 15) of System. byte_ordinal, 

pragma pack (raw 16_bytes) ; 



raw_32_bytes 



type raw_32_bytes is array ( 

System. ordinal range . . 31) of System. byte_ordinal, 

pragma pack(raw_32 bytes); 



raw_64_bytes 



type raw_64_bytes is array ( 

System. ordinal range .. 63) of System. byte_ordinal, 

pragma pack (raw 64 bytes); 



zero to 6 



subtype zero_to_6 is System. ordinal range . . 6; 



zero to 23 



subtype zero_to_23 is System. ordinal range .. 23, 



zero to 59 



subtype zero_to_59 is System. ordinal range . . 59 j 



zero to 99 



subtype zero_to_99 is System. ordinal range .. 99, 
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one to 31 



subtype one to 31 is System. ordinal range 1 



31, 



one to 12 



subtype one_to_12 is System. ordinal range 1 . . 12, 



TOD 



type TOD is 
record 

hundredths_sec : 

seconds: 

minutes: 

wuui s ; 

day_of_week: 
date : 
month : 
year: 
end record; 

for TOD use 
record 

hundredths_sec 

seconds 

minutes 

hours 

day_of_week 

date 

month 

year 
end record; 



zero_to_99 
zero_to_59 
zero_to_59 

zero__to_6 
one_to_31 
one_to_12 
zero to 99 



at range . 

at 1 range . 

at 2 range . 

at 3 range . 

at 4 range . 

at 5 range . 

at 6 range . 

at 7 range . 



Defines the system's TOD counter (in hundredths of a second). 



max error index 



max error index: constant := 27; 



Maximum error record supported (range .. max_error_index). 



max ext box 



max_ext_box: constant System. ordinal := 7; 

Maximum I/O extension box number (range .. max_ext_box). 
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max device index 



max_device_index: constant System. ordinal := 7; 

Maximum device number supported by the System Monitor, (range .. max_device_index). 



max mem rec 



max_mem_rec: constant System. ordinal := 7, 

Maximum record number of a boot or dump image. 



max slot number 



max_slot_number : constant System. ordinal := 13, 

Maximum possible number of slots in a cardcage. 



hw header size 



hw_header_size: constant := 8; 

Size of header portion of hw_entry_rep. 



hw_body_size 



hw_body_size : constant := SCT_Types.hw_entry_size - hw_header_size; 

Size of body portion of hw_entry__rep. 



cardcage_IDjrep 



type cardcage_ID_rep is (sys, ext) ; 



slot number 



subtype slot_number is System. ordinal range .. max_slot_number; 

Although slot represents an invalid number, it is a convenient number to define as a default 
value. 
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module_ID_rep 



type module_ID_rep is 
record 

slot: slot_number; 

don_t_care: two_bit_f ield; 

cardcage: cardcage_ID_rep; 
end record; 

for module_ID_rep use 

record 

slot at range . . 3, 

don_t_care at range 4 . . 5, 

cardcage at range 6 . . 1 , 

end record; 



Fields: 

slot 

Hon +■ rarp Must he initialized to rem 

cardcage 



null module ID 



null_module_ID: constant module_ID_rep := (cardcage => sys, 

don_t_care => 0, 
slot => 0) ; 



AP_bus_reg 



subtype AP_bus_reg is System. ordinal; 

Defines an arbitrary AP-Bus register. 

This type normally represents all AP-Bus registers (in the System Monitor and SCT). This 
type will be retyped to the desired register type only if you need to examine the contents of a 
particular register (e.g. physical ID). 



position 



subtype position is System. ordinal; 

position (sector #) on device 
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physical_addr 



subtype physical_addr is System. ordinal, 

Physical memory address. 



memory_descr 



type memory_descr is 
record 

addr : physical_addr; 

length: System. ordinal; 
end record; 

for memory_descr use 
record 

addr at range . 

length at 4 range . 

end record; 



31, 
31, 



Fields: 

addr 
length 



Start address in memory. 
Length of record in bytes. 



mem rec 



type mem_rec is array (0 .. max_mem_rec) of memory_descr; 

Global types related to I/O devices. 



IO device ID 



type 10 device ID 


is 






record 








io addr: 




System. short ordinal 


application index: 


four bit field; 


don t care : 




three bit field; 


processor: 




one 


bit field; 


module ID: 




module ID rep; 


end record; 








for 10 device ID 


use 






record 








io addr 




at 


range . . 15 


application 


index 


at 


range 16 . . 19 


don t care 




at 


range 20 . . 22 


processor 




at 


range 23 . . 23 


module ID 




at 


range 24 . . 31 


end record; 









Fields: 
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io addr 



Controller address. 



application_index 

Index for identifying a CP application. 

don_t_care Must be initialized to zero. 

processor Local processor ID. 

module ID System bus number and slot number. 



device number 



subtype device_n umber is System. ordinal range .. max_device_index; 



device list 



type device_list is array (device_number) of IO_device_ID, 



null device 



null device: constant 10 device ID 



:= (module_id => null_module_ID, 
processor => 0, 
don_t_care => 0, 
application_index => 0, 
io addr => 16#0000#) ; 



hw_entry_type 



type hw_entry_type is ( 
free, 
cardcage, 
module, 
device) ; 

for hw_entry_type' size use System. storage_unit, 

Types of SCT elements. 

Enumeration Literals: 

free Free element, currently not used. 

cardcage Cardcage entry. 

module Module (board) entry. 

de vi c e Device (boot/console) entry. 
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functional status 



type functional_status is ( 
not_used, 
online, 
offline, 
faulty, 
of fline_or_faulty) ; 

for functional_status' size use System. storage_unit, 



r functional status use ( 






not used 


=> 


0, 


online 


=> 


1, 


offline 


=> 


2, 


faulty 


=> 


3, 


offline or faulty 


=> 


4); 



Possible status of hardware configuration parts. 

Enumeration Literals: 

no t_u s ed Slot is currently not used. 

online Module is available for use. 

offline Module is not available because it is reserved for use by maintenance 

software. 

faulty Module is not available because it is faulty. 

offline_or_faulty 

Module is not available and system cannot determine why. 



componentclass 



type component class is (BXU, MCU) ; 



physical_IDjrep 



type physical_ID_rep is 
record 

class: component_class; 

component: five_bit_f ield; 
end record; 

for physical_ID_rep use 

record 

class at range 5 . . 5, 

component at range . . 4, 

end record; 
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logical_ID_rep 



subtype logical_ID_rep is six_bit_f ield; 

AP-bus logical ID. 



psor_select 



type psor_select is (psor_0, psor_l) ; 

for psor_select use ( 
psor_0 => 0, 
psor 1 => 1) ; 



processor_ID 



type processor_ID is 
record 

unit: logical_ID_rep; 

psor: psor_select; 

zero: one_bit_f ield; 
end record; 

for processor_ID use 

record 

zero at range 
psor at range 1 
unit at range 2 

end record; 



nulI_psor_ID 



null_psor_ID: constant processor_ID := (psor => psor_0, 

unit => 0, 
zero => 0) ; 



arb_ID_rep 



type arb_ID_rep is 
record 

cycle: four_bit_field; 

drive: two_bit_field; 
end record; 

for arb_ID_rep use 

record 

cycle at range ..3, 
drive at range 4 ..5, 

end record; 

AP-bus arbitration ID. 
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invalid arb ID 



invalid arb ID: constant arb_ID_rep := (cycle => 16#F#, 

drive => 16#3#) 



Invalid arbitration ID value, usually given to passive modules. 



error record 



type error_record is 



record 

error_type 
time_stamp: 
unit_name: 
ord_paraml : 
ord_param2 ; 

end record; 



System. short_ordinal, 
raw_6_bytes; 
f ix_16_string; 
System. ordinal; 
System. ordinal; 



for error record use 



record 

error_type 
time_stamp 
ord_paraml 
ord_param2 
unit_name 

end record; 



at range 
at 2 range 
at 8 range 
at 12 range 
at 16 range 



15; 

(6 

31; 

31; 

(16 + 4) 



) - 1, 



Fields: 

error_type 

time_stamp 

unit_name 

ord_paraml 

ord_param2 



Type of error being recorded. 

Time when error was logged. 

Name of module which is associated with the error. 

Parameter #1, meaning defined by error_type. 

Parameter #2, meaning defined by error_type. 



error record size 



error_record_size: constant := 36; 

Size of an error record in bytes. 



error_log_index 



subtype error_log_index is System. ordinal range .. max_error_index; 

Index for entries in SCT's error log. 
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error_log_rep 



type error_log_rep is array ( 
SCT Error log represention . 

This error log is a circular buffer. The 

most recent entry in this buffer must be indicated by an index of 
type error_log_index. 
ror_log_index) of error_record; 

pragma pack (error_log_rep) ; 



error_log_size 



error_log_size: constant := error_record_size * (max_error_index + 1) 

Size of SCT error log in bytes. 



errorjogjrecord 



type error_log_record is 
record 

error_count 

count_time : 

last_error : 

error_log: 
end record; 



System . ordinal ; 
raw_6__bytes; 
error_log_index; 
error_log_rep; 



for error_log_record use 

record 

error_count at range 

count_time at 4 range 

last_error at 12 range 

error_log at 16 range 

end record; 



31; 
. (8'* 6) - 1; 

. 31; 

. error_log size * 



- 1, 



for error_log_record'size use SCT_Types.error_log_size * 8; 

Error Log Record. Used to overlay area in SCT object reserved for error log. 



Fields: 

error_count 
count_time 
last_error 
error_log 



Total number of errors reported, since count_time. 
Time when error_count was last reset to 0. 
Pointer to last entry put into the log. 
Circular buffer used to record error reports. 
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error_log_VA 



type error_log_VA is access error_log_record; 
pragma access kind (error log VA, virtual); 



ext_box_rep 



type ext_box_rep is array (System. ordinal range .. max_ext_box) of boolean; 
pragma pack (ext_box_rep) ; 

Array of flags. If true, extension box is switched on. The list defines one entry for each I/O 
extension box. 



addr_recognizer 



type addr_recognizer is 
record 

mask: AP_bus_reg; 

match: AP__bus_reg; 
end record; 

for addr_recognizer use 
record 

mask at range .. 31; 

match at 4 range . . 31; 
end record; 

Represents address recognizers as defined for the different AP bus agents. 

Every BXU has four address recognizers on its local bus interface and one on its AP bus 
interface. The MCU supports one address recognizer. Space for the other address recognizers 
is not used for MCUs. 

Fields: 

mask Memory window's size. 

match Base address of memory window. 



addr_recognizer_set 



type addr_recognizer_set is array(0 .. 4) of addr_recognizer; 
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null addr rec 



null_addr_rec: constant addr_recognizer_set := ( 

others => (0, 0)); 



Null values for addr recognizers. 



VLSI locations 



type VLSI_locations is ( 
busO, 
busl, 
psorO, 
psorl) ; 



Enumeration Literals: 



busl 

psorO 

psorl 



^uiupuiiciu is ^umic^icu it? at-dus kj. 

Component is connected to AP_Bus l. 
Component is processor on the local bus. 
Component is processor 1 on the local bus. 



VLSI status 



type VLSI_status is array (VLSI_locations) of functional_status; 



VLSI desc 



type VLSI desc is 








record 








physical ID: 


phys 


>ical ID rep; 




logical ID: 


logi 


cal ID rep; 




arb ID: 


arb 


ID rep; 




status : 


VLSI 


status; 




end record; 








for VLSI desc use 








record 








physical ID 


at 


range . . 


7; 


logical ID 


at 


1 range . . 


7; 


arb ID 


at 


2 range . . 


7; 


status 


at 


4 range . . 


31 


end record; 









for VLSI desc' size use 8*8; 
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null VLSI desc 



null_VLSI_desc: constant VLSI_desc := ( 

physical_ID => (BXU, 0), 

logical_ID => 0, 

arb_ID => invalid_arb_ID, 

status => (others => not used) ) 



component_flags 



type component_f lags is array (System. ordinal range .. 3) of boolean; 
pragma pack (component_f lags) ; 

Component flag array. Each position in this array corresponds to a component position on a 
board. 



memory_types 



type memory_types is ( 
not_available, 
DRAM, 
SRAM, 
PROM) ; 

for memory_types use ( 
not_available => 0, 
DRAM => 1, 

SRAM => 2, 

PROM => 3) 



Types of memory modules. 

Enumeration Literals: 

not_available 

Memory module is not available. 

DRAM Memory module contains dynamic RAM. 

SRAM Memory module contains static RAM. 

PROM Memory module contains ROM. 



memory_desc 



type memory_desc is 
record 

mem_type : memory_types; 
index: four_bit_f ield; 
end record; 



for memory_desc use 
record 

index at range . . 3; 

mem_type at range 4 . . 5; 
end record; 
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Breakdown of memory module fields in COM Word 1. 

Fields: 

mem_t y pe Type of memory in this module. 

index Index in system memory module sizes table. 



base boards 



type base_boards is( 
GS2_psor, 
gen_IO, 
BXU_mem, 
MCU_mem, 
f ree_4 , 
free_5, 
free_6, 
f ree_7 , 
GS1_FRC, 
GS1_SBC. 
free_10, 
free_ll, 
free_12, 
free_13, 
free_14, 
GS2_probe) ; 

for base_boards use ( 

GS2_psor => 2#0000#, 

gen_IO => 2#0001#, 

BXU_mem => 2#0010#, 

MCU_mem => 2#0011#, 

free_4 => 2#0100#, 

free_5 => 2#0101#, 

free_6 => 2#0110#, 

free_7 => 2#0111#, 

GS1_FRC => 2#1000#, 

GS1_SBC => 2#1001#, 

free_10 => 2#1010#, 

free_ll => 2#1011#, 

free_12 => 2#1100#, 

free_13 => 2#1101#, 

free_14 => 2#1110#, 

GS2_probe => 2#1111#) 

Known AP-bus base board types. 



IOPMs 



type IOPMs is( 
no_PM, 

low_speed_on_board, 
E_bus, 
LAN_PM, 
HDLC, 
SCSI, 

IPI_master, 
IPI_slave, 

multibus_II_adapter, 
high_speed_on_board) 

for IOPMs use( 
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no PM 




=> 


0, 


low speed on board 


=> 


1, 


E bus 




=> 


2, 


LAN PM 




=> 


3, 


HDLC 




=> 


4, 


SCSI 




=> 


5, 


IP I master 




=> 


6, 


IPI slave 




=> 


7, 


multibus II 


adapter 


=> 


8, 


high speed on board 


=> 


9); 



Known types of IO Personality Modules (IOPMs). 

Enumeration Literals: 

no_PM IOPM not available. 

low_speed_on_board 

E_bus 

LAN_PM 

HDLC 

SCSI 

IPI_master 

IPI_slave 

mu It ibu s_I I_adap t e r 

high_speed_on_board 



IODMs 



type IODMs is( 






no DM, 






digital modem, 






analog_modem) ; 






for IODMs use ( 






no DM 


=> 


0, 


digital modem 


=> 


1, 


analog_modem 


=> 


2); 



Known types of IO Distribution Modules (IODMs). 

Enumeration Literals: 

no__ DM IODM not installed. 

di gi t a l_mo dem 

analog_modem 
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com word 



type com_word (number: two 
record 
parity: 

case number is 
when => 

core : 

core_enabled: 

two_buses : 

CP_fail: 

GDP_fail: 

init_count : 

AP_agents: 

CPs: 

GDPs: 

board_type : 
when 1 => 

artwork_rev: 

assembly_rev: 

buffered: 

memory interleave: 



_bit_field := 0) is 
boolean; 



boolean; 
boolean; 
boolean; 

component_f lags; 
component_f lags; 
two_bit_f ield; 
component_f lags ; 
component_f lags ; 
component_flags; 
base_boards; 

three_bit_field; 
four_bit_f ield; 
boolean; 
two_bit_field; 



on_board_mem : 

mem_mod_B : 

mem_mod_A: 
when 2 => 

reserved_2 : 

IOPM_3 

I0PM_2 

I0PM_1 

IOPM_0 

IODM: 
when 3 => 

uC_f irmware_rev : 

company: 

overf low_rev : 

reserved_3 : 
end case; 
end record; 



memory_desc; 
memory_desc; 
memory_desc; 

nine_bit_f ield; 

IOPMs; 

IOPMs; 

IOPMs; 

IOPMs; 

IODMs; 

System.byte_ordinal; 
one_bit_field; 
System . byt e_ordinal ; 
twelve bit field; 



pragma suppress (discriminant check, com word) 



for com_word use 
record 
number 
parity 
core 

core_enabled 
two_buses 
CP_fail 
GDP_fail 
init_count 
AP_agents 
CPs 
GDPs 

board_type 
artwork_rev 
assembly_rev 
buffered 

memory_inter leave 
memory_initialized 
on_board_mem 
mem_mod_B 
mem_mod_A 
reserved_2 
I0PM_3 
IOPM 2 



at 





range 


30 . 


. 31 


at 





range 


. 


. 0; 


at 





range 


1 . 


. 1; 


at 





range 


2 . 


. 2; 


at 





range 


3 . 


. 3; 


at 





range 


4 . 


. 7; 


at 





range 


8 . 


. 11 


at 





range 


12 . 


. 13 


at 





range 


14 . 


. 17 


at 





range 


18 . 


. 21 


at 





range 


22 . 


. 25 


at 





range 


26 . 


. 29 


at 





range 


1 . 


. 3; 


at 





range 


4 . 


. 7; 


at 





range 


8 . 


. 8; 


at 





range 


9 . 


. 10 


at 





range 


11 . 


. 11 


at 





range 


12 . 


. 17 


at 





range 


18 . 


. 23 


at 





range 


24 . 


. 29 


at 





range 


1 . 


. 9; 


at 





range 


10 . 


. 13 


at 





range 


14 . 


. 17 
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I0PM_1 
IOPM_0 
IODM 

uC_f irmware_rev 
company 
overflow_rev 
reserved_3 
end record; 



at 





range 


18 . 


. 21 


at 





range 


22 . 


. 25 


at 





range 


26 . 


. 29 


at 





range 


1 . 


. 8; 


at 





range 


9 . 


. 9; 


at 





range 


10 . 


. 17 


at 





range 


18 . 


. 29 



Fields: 

number 

parity 

core 

core_enabled 

two__buses 

CP_fail 

GDP_fail 

init_count 

AP_agents 

CPs 

GDPs 

board_type 

artwork_rev 

assembly_rev 

buffered 

memory_inter leave 

memory_initialized 

on_board__mem 

mem_mod_B 

mem_mod_A 

reserved_2 

IOPM_3 

IOPM_2 

IOPM_l 

IOPM_0 

IODM 

uC_firmware__rev 

company 

overf low_rev 

reserved 3 



Format of COM Words. 

Odd parity bit for all COM words. 
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invalid com word 



invalid_com_word: constant com_word(3) := ( 
Invalid value for COM word. 

number => 3, 

reserved_3 => 0, 
uC_f irmware_rev => 0, 
company => 0, 
overflow_rev => 0, 
parity => false) 



env status bits 



type env_status_bits is ( 
PSaO_installed, 
PSal_installed, 
PSbO_installed, 
PSbl_installed, 
PSaO 5v failed, 
PSa0_12v_f ailed, 
PSal_5v_failed, 
PSal_12v_failed, 
PSbO_failed, 
PSbl_failed, 
buf_5v_f ailed, 
other_AC_down, 
UPS_on, 

sys_batt_f ault , 
extrn_batt_fault, 
PS_temp_fault, 
cage_temp_fault, 
periph_temp_fault, 
air_intake_fault, 
blower_fault, 
box0_fault, 
boxl_fault, 
box2_fault, 
box3_fault, 
reserved_l, 
reserved_2, 
reserved_3, 
reserved_4 , 
reserved_5, 
reserved_6, 
reserved_7, 
reserved 8) ; 



Enumeration Literals: 

PSaO_installed 

Power Supply A:0 installed. 

PSal_installed 

Power Supply A:l installed. 

PSbO_installed 

Power Supply B:0 installed. 

PSbl_installed 

Power Supply B:l installed. 
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PSaO_5v_failed 

Power Supply A:0 5 volt failed. 

PSaO_12v_failed 

Power Supply A:0 12 volt failed. 

PSal_5v_f ailed 

Power Supply A:l 5 volt failed. 

PSal_12v_failed 

Power Supply A:l 12 volt failed. 

PSbO_f ailed Power Supply B:0 failed. 

PSbl_f ailed Power Supply B:l failed. 

buf_5v_f ailed 

Buffered 5 volt supply failed. 

other_AC_down 

AC feed to other Power Supply C down. 

UP S_on Uninterruptable Power Supply on. 

sys__batt_fault 

Internal system battery failed. 

extrn_batt_fault 

External battery failed. 

PS_temp_fault 

Temperature fault in power supply. 

cage_temp_fault 

Temperature fault in cardcage. 

periph_temp_fault 

Temperature fault in peripheral area. 

air_intake_fault 

Temperature fault in air intake. 

Blower fault 

Fault signalled by Extension Box 0. 

Fault signalled by Extension Box 1. 

Fault signalled by Extension Box 2. 

Fault signalled by Extension Box 3. 

reserved for future expansion. 

reserved for future expansion. 

reserved for future expansion. 

reserved for future expansion. 

reserved for future expansion. 

reserved for future expansion. 

reserved for future expansion. 

reserved for future expansion. 



blower_fault 

boxO_fault 

boxl_fault 

box2_fault 

box3_fault 

reserved_l 

reserved_2 

reserved_3 

reserved_4 

reserved_5 

reserved_6 

reserved_7 

reserved 8 
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env status array 



type env_status_array is array (one_bit_field, env_status_bits) of boolean; 
pragma pack (env_status_array) ; 

This two dimensional array is used to completely describe the environmental status of the 
system and extension containers, in the largest possible system. The first index selects the 
SSM which is provided the information, and the second index selects an environmental status 
■bit 



env_status_array_size 



env_status_array_size: constant := 2 * 32; 

for env_status_array' size use env_status_array_size; 

Maximum sixe m eiivirunnieiiud siaius array (2 SSMs and 52 siaius buoleans per SSivi); 



cardcage_rep 



type cardcage rep is 










record 












num slots: 




System. byte ordinal 


two bus system: 


boolean; 






status bus 




boolean; 






status bus 1 




boolean; 






status SSB 




boolean; 






status SSB 1 




boolean; 






SSMO link: 




slot 


number ; 




SSM1 link: 




slot 


number ; 




io ext box: 




ext box , 


rep; 




box type : 




System. byte ordinal 


env status: 




env status array; 


end record; 












for cardcage r« 


»p use 








record 












num slots 




at 





range 


. . 


two bus sys 


stem 


at 


2 


range 


.. 


status bus 





at 


3 


range 


. . 


status bus 


1 


at 


4 


range 


. . 


status SSB 





at 


5 


range 


.. 


status SSB 


1 


at 


6 


range 


. . 


SSMO link 




at 


7 


range 


. . 


SSM1 link 




at 


8 


range 


. . 


io ext box 




at 


11 


range 


. . 


box_type 




at 


12 


range 


. . 


env status 




at 


13 


range 


. . 


end record; 













7; 

7 

7 

7 

7 

7 

7 

7 

7 

7 

env status array size - 1, 



for cardcage_rep'size use hw_body_size*i 



bus info: 



Fields: 
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num slots 



Number of slots on backplane. 



two bus system 



status_bus_0 

status_bus_l 

status_SSB_0 

status_SSB_l 

SSM0_link 

SSMl_link 

io_ext_box 

box_type 

env status 



If true, two bus system. 

Iftrue,GOAP-BusO. 

Iftrue,GOAP-Busl. 

Iftrue,GOSSB0. 

If true, GO SSB 1 (Serial System Bus). 

Slot number on which the SSM1 connection is established. 

Slot number on which the SSM2 connection is established. 

Status of io_extension_boxes. 

Enclosure or box type. This is the type of physical package in which the 
cardcage is housed. This byte is heavily encoded, to decode it, retype it to 
be of type SSM_Def s . ssm_loc_rec. 

Environmental status for the System and Extension containers. 



module_rep 



type module_rep is 
record 

diag_lock: 

slot : 

spouse : 

buffered: 

FRC_err_count : 

FRC_d: 

QMR_d: 

primary: 

VLSI_master : 

VLSI_checker: 

com_0 

com_l 

com_2 

com_3 

re s_0 

res_l 

conf ig_request_param : 

memory_size: 

bus__interleaved : 

cache_status : 

addr_recognizer: 
res_2 : 
end record; 

for module_rep use 
record 

diag_lock 

slot 

spouse 

buffered 

FRC_err__count 

FRC_d 

QMR_d 

primary 

VLSI_master 

VLSI_checker 

com_0 

com_l 

com_2 

com 3 



System. ordinal; 

slot_number; 

slot_number; 

boolean; 

System . byte_ordinal ; 

boolean; 

boolean; 

boolean; 

VLSI_desc; 

VLSI_desc; 

com_word; 

com_word; 

com_word; 

com_word; 

System . ordinal ; 

System. ordinal; 

System. ordinal; 

System . ordinal ; 

boolean; 

functional_status; 

addr_recognizer_set; 

System . ordinal ; 



at 
at 
at 
at 
at 
at 
at 
at 
at 
at 
at 
at 
at 
at 



9 
16 
24 
32 

36 

40 
44 



range 
range 
range 
range 
range 
range 
range 
range 
range 
range 
range 
range 
range 
range 



31; 

7, 

7 

7 

7 



1 

2 

8*8-1, 

8*8-1, 

31, 

31 

31 

31 
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res_0 




at 


48 


range 


. 


31; 


res 1 




at 


52 


range 


. 


31; 


conf ig 


_request_param 


at 


56 


range 


. 


31; 


memory 


size 


at 


64 


range 


. 


31; 


bus_inter leaved 


at 


68 


range 


. 


7; 


cache 


status 


at 


69 


range 


. 


7; 


addr__recogni zer 


at 


72 


range 


. 


5*8*8-1 


res_2 




at 


112 


range 


. 


31; 


end record; 













for module_rep' size use hw_body_size*8; 



Fields: 

diag__lock 



slot 

spouse 

buffered 

FRC_err_count 

FRC_d 

QMR_d 

primary 

VLSI_master 

VLSI_checker 

com_0 

com 1 



If not equal to zero then, this module has been reserved by a diagnostic or 
maintenance process and other processes should not attempt to access the 
AP-Bus agents on it. The non-zero value used to reserve a module is the 
reserving process' ID, which is the binary form of the process' AD. 

Slot number of module. 

Slot number of spouse module. 

The memory on this module was battery backed-up when INIT occurred 
(corresponds to the (AP_Bus agents WARM START bit) 

Number of FRC errors occurred (used to identify transient errors). 

If true, the module is FRC'd. 

If true, this module is QMR'd. 

If true, this module is the hardware defined PRIMARY. 

VLSI IDs and status MASTER bus. 

VLSI IDs and status CHECKER bus. 

COM words contain board configuration information, such as board type 
and VLSI. 



Configuration, IO_distribution module type, INIT_counter, CTRL-bits, 
IO_personality. 

com_2 Module types, layout type, and revision level. 

com_3 Extended revision level. 

r e s_0 Reserved for additional board-level information. 

re s_l Reserved for additional board-level information. 

conf ig_request_param 

Configuration parameters copied from Parameter Store. 

memory_s i z e Memory available on module (size in bytes). 

bus_interleaved 

If true, this module has its address recognizer set for bus interleaving. 

cache_st at us Status of the on-board cache. 

addr_recognizer 

Address recognizer values for up to five recognizers (i.e., for one BXU of 
a module); note, the second BXU has the same set, or can be derived out 
of this set (e.g., in case of interleaving). 
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res 2 



Handle to allow using the additional space using external type definitions 
as long as this definition is not yet updated. 



nulI_moduIe_rep 



null module rep: 



constant module 


rep : = 


( 




diag lock 




=> 


0, 


slot 




=> 


o, 


spouse 




=> 


o, 


buffered 




=> 


false, 


FRC err count 




=> 


o, 


FRC d 




=> 


false, 


QMR d 




=> 


false, 


primary 




=> 


false, 


VLSI master 




=> 


null VLSI desc, 


VLSI checker 




=> 


null VLSI desc, 


com 




=> 


invalid com word, 


com 1 




=> 


invalid com word, 


com 2 




=> 


invalid com word, 


com 3 




=> 


invalid com word, 


res 




=> 


0, 


res 1 




=> 


0, 


config request_param 


=> 


0, 


memory size 




=> 


0, 


bus interleaved 


=> 


false, 


cache status 




=> 


offline, 


addr recognizer 


=> 


null addr rec, 


res 2 




=> 


0); 



IO_application 



type IO_application is ( 

unused, ASYNC, HDLC_LS, HDLC_HS, LAN, SCSI, IPI, SSB, EDS) 

for 10 application' size use 8; 



device_param_rep 



type device_param_rep is array (0 .. 1) of raw_64_bytes; 

An SCT device entry can hold two Parameter Store device parameter entries. 



devicejrep 



type device_rep is 

record 
level: 

device_f lavor : 
device_ID: 
parameter: 

end record; 



System . byte_ordinal , 
IO_application; 
IO_device_ID; 
device_param__rep; 



for device_rep use 
record 

level at range . 

device_flavor at 3 range . 



. 7, 
. 7, 
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at 4 range . . 31; 

at 16 range .. 2*64*8-1, 



for device_rep' size use hw__body_size*8; 



Fields: 

level 



device_f lavor 

device_ID 
parameter 



Identifies auxiliary entries used to record additional I/O parameters for a 
device. If this entry is equal to then is this the master entry for the 
device. If it is not equal to this entry contains extra params. which did 
not fit into the master entry. 

Type of application required to handle the device (used to identify CP 
application and Device Driver) 

Device ID of the device to which this entry belongs. 

Array of device-specific parameters to be used in Device Object. 



hardware_entry_rep 



type hardware_entry_rep (entry_type: hw_entry_type 
record 

cardcage_ID: cardcage_ID_rep; 
status: functional_status; 

case entry_type is 



= cardcage) is 



cardcage_rep ; 
module_rep; 
device rep; 



when cardcage => 

cardcage : 
when module => 

module : 
when device => 

device : 
when free => 

null; 

end case; 

end record; 



pragma suppress (discriminant_check,hardware_entry_rep) ; 



for hardware_entry_rep use 



record 




entry_type 


at 


cardcage ID 


at 


status 


at 


cardcage 


at 


module 


at 


device 


at 


end record; 





range . . 7 

1 range . . 7 
3 range . . 7 
hw_header_size 
hw_header_size 
hw header size 



range . . hw_body_size*8-l 
range . . hw_body_size*8-l 
range . . hw_body_size*8-l 



for hardware_entry_rep'size use SCT_Types.hw_entry_size * 8 

Fields: 

entry_type 

cardcage_lD Indicates which cardcage this module is associated with. 

st at us Current status of the corresponding configuration part, 

cardcage This entry describes a cardcage. 
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module This entry describes a module (i.e. board), 

de vi ce This entry describes a boot or console device. 



hardware_entry_VA 



type hardware_entry_VA is access hardware_entry_rep; 
pragma access_kind (hardware_entry_VA, virtual); 



hardware entry_header 



type hardware_entry_header is 
record 

entry_type : hw_entry_type; 

cardcage_ID: cardcage_ID_rep; 

status: functional_status; 
end record; 

for hardware_entry_header use 
record 

entry_type at range . . 7 

cardcage_ID at 1 range . . 7 

status at 3 range . . 7 

end record; 

Used by the System Monitor to do partial initialization of hardware entries. The representation 
of this type must match the representation for the header portion of hardware_ent ry__rep. 



system_type_rep 



type system_type_rep is ( 
GS_0, 
GS_1, 
GS_2 f 
SIM) ; 

for system_type_rep use ( 
GS_0 => 0, 
GS_1 => 1, 
GS_2 => 2, 
SIM => 3) ; 



Enumeration Literals: 

GS_0 Identifies a GS system. 

GS_1 Identifies a GS 1 system. 

GS_2 Identifies a GS 2 system. 

S IM For debugging only. 
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system_mode_rep 



type system_mode_rep is (normal, 

diagnostic_required, 
diagnostic_ready, 
diagnostic, 
diagnostic_done) ; 



Enumeration Literals: 

normal System is configured for and running in normal system operation mode. 

diagnostic_required 

System is running, but requests to get transferred to diagnostic mode. 

diagno st ic_r eady 

System has been reconfigured and is ready to run in diagnostic mode. 

diagno st ic System is configured for and running in diagnostic mode. 

diaanostic_done 

System is ready to get reconfigured for normal mode of operation. 



sm_ctrl_param 



type sm ctrljparam is 




record 






gdp test : 


boolean; 


cp test: 


boole 


an; 


bxu test : 


boolean; 


mem Ctrl test: 


boolean; 


mem_array test: 


boole 


an; 


spare console: 


boolean; 


spare boot dev: 


boolean; 


spare image: 


boolean; 


auto dump: 


boolean; 


auto continue: 


boolean; 


auto mask: 


boole 


an; 


load: 


boolean; 


start: 


boolean; 


end record; 






for sm Ctrl param 


use 




record 






gdp test 


at 





cp test 


at 





bxu test 


at 





mem Ctrl test 


at 





mem_array test 


at 





spare console 


at 


2 


sparejboot dev 


at 


2 


spare image 


at 


2 


auto dump 


at 


3 


auto continue 


at 


3 


auto mask 


at 


3 


load 


at 


3 


start 


at 


3 


end record; 







range 
range 1 
range 2 
range 3 
range 4 
range 
range 1 
range 2 
range 
range 1 
range 2 
range 6 
range 7 



System Monitor's control parameters. System software may use those entries to control the 
System Monitor's behavior during the next initialization sequence. 
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Fields: 

gdp_test 
cp_test 



Enables GDP confidence test. 
Enables CP confidence test. 
bxu_t est Enables BXU confidence test. 

mem Ctrl test 



Enables memory controller test, either (MCU or BXU). 

mem_array_test 

Enables memory array testing. 

spare_console 

Enables spare system console. 

spare_boot_dev 

Enables spare boot device. 

spare_image Enables spare boot image. 

auto_dump Enables auto dump. 

auto_continue 

If true, forces the System Monitor to continue operation in the auto mode 
after failures (e.g. error during dumping). 

Used to force entering the System Monitor's manual mode in cases the 
system normally would perform an AUTO_START (e.g. restart after 
power failure) when the System Monitor had been active before the PF 
occurred. 

If true, forces the System Monitor to load an image. 

If true, enables the System Monitor to activate booted image System Con- 
figuration Table. 



auto mask 



load 
start 



number_of_ranges 



number of ranges: constant := 8; 



Maximum number of special memory ranges which can be allocated. 



range description 



type range_description is 



record 

valid: 

start_pa : 

size__in_pages : 

cacheable: 

AD: 
end record; 



boolean; 

physical_addr; 

System . short_ordinal ; 

boolean; 

System. untyped word; 



for range_description use 



record 

valid 

cacheable 

size_in_pages 

start_pa 

AD 
end record; 



at 
at 
at 
at 
at 



range 

1 range 

2 range 
4 range 
8 range 



7; 
7; 
15 
31 
31 
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Fields: 

valid If true, This range description is valid. 

s t ar t_pa Starting physical address of range, must be on a page boundary. 

s i z e_i n_pa ge s 

Number of contiguous pages reserved for object. 

cacheable If true/Object is cacheable. 

AD Access Descriptor, created and filled in by SBL, which points to memory 

described by this record. 



memory_ranges 



type memory_ranges is array(l .. number_of_ranges) of range_description; 
pragma pack (memo ry_ranges) ; 

I software_entry 



type software entry . 


.s 




record 






system_type: 


system type rep; 




system_subtype : 


System. short ordinal; 




system_mode : 


system_mode_rep; 




conf_complete : 


boolean; 




start_event : 


system_start_e vent ; 




sm ctrl: 


sm_ctrl param; 




FT_config: 


raw_8_bytes; 




init_count : 


System . ordinal ; 




max_count : 


System . ordinal ; 




dev: 


device list; 




SM OT: 


physical addr; 




SM_PRCB: 


physical_addr; 




SM res 1 




System. untyped word; 




SM res 2 




System. untyped word; 




SM res 3 




System. untyped word; 




self_IAC 




System. untyped word; 




reserved memory: 


memory ranges; 




image_version : 


raw_32_byt es ; 




image_addr : 


mem rec; 




image OT: 


phys ical_addr ; 




image_PRCB : 


physical_addr; 




dump_dev : 


IO_device_ID; 




dump_posit ion : 


position; 




dump_rec : 


mem rec; 




spare boot_pos : 


position; 




MM_IO: 


System . address ; 




control_reg: 


System . byte_ordinal ; 




end record; 






for software entry 


use 




record 






system type 


at range . 


7; 


system subtype 


at 1 range . 


15 


system_mode 


at 4 range . 


7; 


start_event 


at 5 range . . 


7; 


conf_complete 


at 6 range . . 


7; 


sm_ctrl 


at 8 range . . 


31 


init__count 


at 12 range . . 


31 


max_count 


at 16 range . * 


31 


FT_config 


at 20 range . . 


63 
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dev 


at 


32 


range 


. 


. 32*8-1; 






SM OT 


at 


64 


range 


. 


. 31, 








SM PRCB 


at 


68 


range 


. 


. 31, 








SM res 1 


at 


72 


range 


. 


. 31, 








SM res 2 


at 


76 


range 


. 


. 31 








SM res 3 


at 


80 


range 


. 


. 31 








self_IAC 


at 


84 


range 


. 


. 31 








reserved memory 


at 


96 


range 


. 


. 12*number 


of ranges*8- 


-1 


image_version 


at 


256 


range 


. 


. 32*8-1; 






image_addr 


at 


288 


range 


. 


. 64*8-1; 






image OT 


at 


352 


range 


. 


. 31 








image_PRCB 


at 


356 


range 


. 


. 31 








dump_dev 


at 


360 


range 


. 


. 31 








dumpjposition 


at 


364 


range 


. 


. 31 








dump_rec 


at 


368 


range 


. 


. 64*8-1; 






spare boot pos 


at 


432 


range 


. 


. 31 








MM_IO 


at 


484 


range 


. 


. 63 








control_reg 


at 


492 


range 


. 


. 7 








end record; 



















for software_entry' size use SCT_Types. sys_sw_size * 8; 

Contains user visible information from the software entry. 

Fields: 

sy st em_type Type of system (e.g. GS2). 

system_subtype 

Differentiates system flavors (initialized with value from Parameter 
Store). 

system_mode Mode in which the system is currently operating. 

conf complete 



start_event 
sm Ctrl 



FT_config 
init count 



max_count 
dev 

SM_OT 

SM_PRCB 

SM_res_l 

SM_res_2 

SM_res_3 

self IAC 



If true, the system has been completely configured. 

Event which caused the system start. 

Control parameter set used by the System Monitor to control the next init 
sequence. The parameters are set to default if the SCT has to be built 
before activating the loaded image. They can be set by the current image if 
a particular init sequence is desired with the next system restart. 

FT configuration parameters from Parameter Store. 

Counter will be initialized with 0; every time the start event is a h/w- 
driven watchdog timer reset, INIT_COUNT will be incremented. Re-init 
stops if count exceeds MAX_COUNT; the counter has to be reset by the 
booted image. 

Threshold value for INIT_COUNT. 

List of eightr device aliases. 0: default System Console 1: default Boot 
Device 2: spare System Console 3: spare Boot Device 4-7: not predefined 

Physical addresses of Object 

Table (OT) and Processor Control Block (PRCB). 

Reserved for System Monitor. 

Reserved for System Monitor. 

Reserved for System Monitor. 

AD to an object that allows to send an IAC to itself. 
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reserved_memory 

List of special reseved memory ranges for which SBL must create objects. 



image_version 



ID, version number, and date of the image loaded. During auto dumping 
used as ID for the dump data, hence, system software should set this field 
appropriately. Also note, version number gets incremented by one with 
every dump. 

Start addresses and lengths of the image's records 

physical addresses of Object 

Table (OT) and Processor Control Block (PRCB). 

Information to perform auto dumping. 



image_addr 
image_OT 
image_PRCB 
dump_dev 
dump_po s it ion 

dump_rec 

spare_boot_j?os 

Position of spare image (i.e. spare VSM disk header) on primary 
boot device (0: disk does not provide spare image). 

MM_lO Virtual address allowing DDs to access I/O registers. 

control_reg Actual control register value. 



Information to perform auto dumping. 
Information to perform auto dumping. 



software_entry_VA 



type software_entry_VA is access software_entry; 
pragma access_kind (software_entry_VA, virtual); 



hw_info_rep 



type hw_info_rep is 
record 

num_system_buses : 
num_slots: 
num_GDP : 
num_CP : 

stable_mem_addr : 
stable_mem_length : 
interl_mem_addr : 
inter l_mem_length: 
non_interl_mem_addr : 
non_interl_mem_length : 
end record; 



for hw info rep use 






record 






num system buses 


at 





num slots 


at 


1 


num GDP 


at 


2 


num CP 


at 


3 


stable mem addr 


at 


4 


stable mem length 


at 


8 


interl mem addr 


at 


12 


interl mem length 


at 


16 


non interl mem addr 


at 


20 


non_interl_mem_length 


at 


24 



System . byte_ordinal ; 
System . byte_ordinal ; 
System . byte_ordinal ; 
System . byte_ordinal j 
phy s i ca l_addr ; 
System. ordinal; 
physical_addr; 
System. ordinal; 
physical_addr; 
System. ordinal; 



range 
range 
range 
range 
range 
range 
range 
range 
range 
range 



7 
7 
7 
7 

31 
31 
31 
31 
31 
31 
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end record; 
pragma external; 

Hardware summary information record. 

Fields: 

num_system_buses 

Number of system buses. 

num_s lots Number of slots in cardcage. 

num_GDP Number physical GDPs. 

num_CP Number physical CPs. 

s t ab 1 e_mem_a ddr 

Physical start address (byte). 

s t ab 1 e_mem_l e n gt h 

Size in bytes. 

int e r l_mem_addr 

Physical start address (byte). 

inter l_mem_length 

Size in bytes. 

non_interl_mem_addr 

Physical start address (byte). 

non_interl_mem_length 
Size in bytes. 
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SCT Access 



Provides access to the System Configuration Table (SCT). 

Security 



Calls 



Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



Get_error_log 

Retrieves the error log record from the SCT. 

Get_hardware_info 

Gets hardware information about a cardcage. 

Release_hw_entries 

Reserves modules which have already been reserved by the calling process. 

Re s e r ve_hw_e nt r i e s 

Reserves the specified modules entries in SCT and returns the list of modules in 
the cardcage. 

Retrieve__cardcage_entries 

Returns a record which contains an entry describing the selected modules in the 
designated cardcage. 

Retrieve_device_entry 

Retrieves information stored in the SCT about a device. 

Retrieve_software_entry 

Extracts user visible information from the SCT's software entry and returns this 
information in a record. 

Set_system_monitor_j?arameters 

Sets the System Monitor parameters in the SCT's software entry. 



Summary 

This package provides access to the SCT using four types: 



• Retrieve functions return records which contain images of various entries in the SCT 
(card-module, device, or cardcage entries). 
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• The Set procedure allows the caller to set the System Monitor's control parameters. 

• Reserve/Release functions allow the caller to reserve and release various card- 
modules in a cardcage. 

• The Get procedure returns either the summary for the SCT hardware information (that is, 
data on modules in a particular cardcage) or it's error logs. 

This package provides you with read access only to the System Configuration Table except for 
the System Monitor control parameters in the software entry. 

The SCT consists of three parts. The first part includes the system software entry which con- 
tains information used by the system software to configure the system. 

The second part contains an error log. The error log is a circular buffer that records the most 
recent hardware-related errors. It also contains a total error count field which can be used to 
detect an error log overflow. 

The third part of the SCT contains the hardware entries. These entries contain a detailed 
description of the current hardware configuration. 



Exceptions 



reserved_by_pthers 

An attempt was made to reserve modules already reserved by another process or 
release a module already reserved by another process, using a Reserve or 
Release function. 

not_in_SCT 

Indicates a non-existant HW entry in the SCT. 

inconsistent_data 

Indicates an attempt to update the SCT with corrupt data. 



SCT Access=2 



PRELIMINARY 



Declarations 



max_parameter_number 



max_parameter_number : constant := 8; 

Maximum number of parameters for each 10 device in the SCTs device list. 



free_hw_entry 



free_hw_entry: constant KMDS_Def s . hardware_entry_rep 
(entry_type => KMDS_Def s . f ree, 
cardcage_ID => KMDS_Defs. sys, 
status => KMDS Defs.not used) 



HW entry of type free. 



module array 



type module_array is array ( 
System. ordinal range 
.. KMDS_Defs.max_slot_number) of KMDS_Def s .hardware_entry_rep; 

List of module data, in a cardcage. 



entry_list 



type entry_list is 
record 

cardcage: KMDS_Defs.hardware_entry_repj 

modules: module_array; 
end record; 



List of entries. 



parameter_array 



type parameter_array is array ( 

1 .. max_parameter_number) of KMDS_Defs.device_param_rep; 

Define the data structures that hold device entry information retrieved either from the SCT, or 
information used to update the SCT. 
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device_entry 



type device entry is 



record 

cardcage_ID : 
status : 
module : 
device_ID: 
param_length: 
parameters : 

end record; 



KMDS_Defs . cardcage_ID_rep; 
KMDS_Defs . f unctional_status, 
KMDS_Defs.slot_number; 
KMDS_Def s . IO_device_ID; 
System. ordinal; 
parameter array; 



The following fields define pertinent elements of the device. 

Fields: 

cardcage_lD ID of the cardcage device belongs to. 

s t at u s Functional status of the device. 

mo du le Slot number of the device. 

device_ID Device ID information. 

param_length The number of entries placed in the parameter field. 

parameters Device parameters. 



reserve_by_option 



type reserve_by_option is ( 

physical__ID, logical_ID, slot_number, ignore) ; 

for reserve_by_option' size use System. storage_unit , 

Module identification options to reserve modules in a cardcage. 



module_reserve__options 



type module_reserve_options ( 

option: reserve_by_option := physical_ID) is 
record 

case option is 

when physical_ID => 

phys_ID: KMDS_Defs.physical_ID_rep; 
when logical_ID => 

logic_ID : KMDS_Def s . logical_ID_rep; 
when slot_number => 

slot__num: KMDS_Defs .slot_number; 
when ignore => 
null; 
end case; 
end record; 

pragma suppress (discriminant_check,module_reserve_options) 

for module_reserve_options use 
record 

option at range . . 7 
phys_ID at 1 range . . 7 
logic_ID at 1 range . . 7 
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slot_nura at 1 range .. 7; 

end record; 

Reserve the module with this physical ID. 

Fields: 

option 

phys_ID 

logi c_ID Reserve the module with this logical_ID. 

slot num Reserve the module with this slot_number. 



moduIe_entries_array 



type module_entries_array is array ( 

1 .. KMDS_Defs.max_slot_number) of module_reserve_options; 

Array type specifies a set of modules in a cardcage with it's slot number, VLSI physical_ 
ID, or VLSI logical_ID. Reserve and Release functions then use it to reserve or release 
the modules in a cardcage. To specify the ID of each module, you need to set the option field 
of each array entry as defined by module_reserve__opt ions record declaration. 



dont care list 



dont_care_list : constant module_entries_array := module_entries_array' ( 
1 .. KMDS_Defs.max_slot_number => (option => ignore)); 

Denotes an empty list of modules passed to Re s erve_hw_ent r ie s when the list of 
modules to reserve is not needed (reserving all modules in the cardcage), and passed to 
Release_hw_entries when the list of modules to release is not needed. This releases all 
modules in the cardcage reserved by the current process. 



requestedmodules 



type requested_modules is ( 

all_modules, cardcage, offline, bad) ; 

Used by the retrieve functions to indicate what set of modules in the cardcage to retrieve 
information from. 

• all_modules : Retrieve info from all modules in cardcage. 

• cardcage: Retrieve info from the cardcage entry, only. 

• offline: Retrieve info from modules with functional status of offline in cardcage. 

• bad: Retrieve info from modules with functional status of offline, faulty, or, 
of f line_or_f aulty in cardcage. 
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Get_errorJog 



function Get_error_log ( 

zerc_error_count : boolean := false) 
return KMDS_Def s . error_log_record; 
pragma outerface (value, Get error log); 



Parameters 



zero_error_count 

A directive to zero (clear) out the error count field (total number of errors 
logged) in the System Configuration Table. 

Return Type and Value 

KMDS_Def s . error_log_record 

The retrieved fault record. 

Operation 

Retrieves the error log record from the SCT. 

If zero_error_count is true, the SCT error count is set to zero. 

Exceptions 

not in SCT 
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Get hardware info 



function Get_hardware_info ( 

cardcage_ID : KMDS_Def s . cardcage_ID_rep) 
return KMDS_Defs .hw_info_rep; 
pragma outerface (value, Get_hardware_inf o) ; 

Parameters 

cardcage_ID ID of cardcage to access. 

Return Type and Value 

KMDS_Def s . hw_inf o_rep 

Summary of cardcage hardware information. 

Operation 

Gets hardware information about a cardcage. 

Scans through the entire System Configuration Table, gathers all the hardware information 
belonging to the indicated cardcage, and returns a summary of this information. 

Exceptions 

not in SCT 
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Release hw entries 



function Release_hw_entries { 

cardcage_ID: KMDS_Defs.cardcage_ID_rep; 

release_list : module_entries_array := dont_care_list, 

force: boolean := false; 

every_module : boolean := true) 
return module_entries_array; 
pragma outerface (value, Release_hw_entries) ; 



Parameters 

cardcage_ID 

release_list 

force 

every_module 



ID of the cardcage to be accessed. 

List of modules to be released. 

Release the specified module entries regardless of who had reserved them 
originally, when set to true. 

If true, release every module reserved by the caller. 



module_entries_array 

List of modules that were released. 



Operation 



Warning 



Notes 



Reserves modules which have already been reserved by the calling process. 

The list of modules to be released is specified by release_JList. Modules in this list must 
be identified through their physical_ID, logical_ID, or slot_number. Therefore, it 
is possible to specify a list of modules within a cardcage identified through different types of 
ID'S. 

If every__module is true, the function releases every module in the cardcage already 
reserved by the caller. The fist of returned modules is returned for the caller's verification and 
must be identical to release list. 



Improper use of force may result in unpredictable diagnostics behavior and results. 



Modules are released by the caller's process ID. If any of the modules specified in releasejist 
are reserved by another process ID, then none of the modules in this list are released, and an 
exception is raised. 

force forces the release of module entries which are reserved with a process number dif- 
ferent than that of the caller. It should only be used to release those module entries that are 
remained reserved by processes that no longer exist (i.e. abnormally terminated). 
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Exceptions 

not_in_SCT 
reserved__by_others 
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Reserve hw entries 



function Reserve_hw_entries { 

cardcage_ID : KMDS_Def s .cardcage_ID_rep; 

reserve_list : module_entries_array := dont_care_list; 

force: boolean := false; 

every_module : boolean := true) 
return module_entries_array; 
pragma outerface (value, Reserve hw entries); 



Parameters 



cardcage_ID 

reserve_list 

force 



ID of the cardcage to be accessed. 

List of modules to be reserved. 

Reserve the specified module entries regardless of who had reserved them 
originally, when set to true. 

ever y_module Reserve every module, if true. 



module_entries_array 

List of modules that were reserved. 



Operation 



Warning 



Notes 



Reserves the specified modules entries in SCT and returns the list of modules in the cardcage. 

The returned list of modules include the given ID (cardcage_ID) reserved for the caller. 

reserve_list specifies the list of modules to reserve. The caller should specify their 
identity through the module's physical_ID, logical_ID, or slot_number. Any entry 
set to ignore is ignored. This allows you to specify a list of modules within a cardcage 
reserved through different ID options. The list of reserved modules is returned for the caller's 
verification and must be identical to reserve_list. 

If every_module is true, every module in the cardcage is reserved. 



Improper use of this parameter may result in unpredictable diagnostics behavior and results. 



Modules are reserved by the caller's process ID. If any of the modules specified in 
reserve_list are reserved by another process ID, then none of the modules in this list are 
reserved, and an exception is raised. 

force forces reservation of module entries which have a different process number than that 
of the caller. It should only be used to reserve those module entries that remain reserved with 
processes that no longer exist (i.e. abnormally terminated). 
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Exceptions 

not_in_SCT 
reserved by others 
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Retrieve__cardcage_entries 



function Retrieve_cardcage_entries ( 

cardcage: KMDS_Defs .cardcage_ID_rep; 

modules: reguested_modules := all_modul.es) 
return entry_list; 
pragma outerf ace (value, Retrieve_cardcage_entries) ; 

Parameters 

cardcage ID of cardcage entry from which to retrieve information. 

module s Set of module entries in cardcage from which to retrieve information. 

Return Type and Value 

ent ry_li st Record of all modules in the cardcage. 



Operation 



Notes 



Returns a record which contains an entry describing the selected modules in the designated 
cardcage. 

The contents of modules defines the set of modules to retrieve, as follows: 

"all_modules" : Retrieve information about every module. 

"offline": Retrieve information about modules with 
functional status of "offline". 

"bad": Retrieve information about modules with 

functional status of "offline", 
"faulty", or "offline_or faulty". 



Entries in the returned array are indexed by their slot number. For example, if a module entry 
resides on slot 5, the procedure places it in the fifth entry of the array. It then sets the unused 
entries in the array to f ree_hw_entry. 



Exceptions 

not in SCT 
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Retrieve_device_entry 



function Retrieve_device_entry ( 

device_num: KMDS_Defs .device_number) 
return device_entry; 
pragma outerface (value, Retrieve_device_entry) ; 

Parameters 

de vi c e_num Number of device to for which to retrieve information. 

Return Type and Value 

de vi ce_ent ry Information about device. 

Operation 

Retrieves information stored in the SCT about a device. 

device_num is the displacement of the device's ID in the software entries device list. For 
example, if the caller wanted to retrieve information about the actual System Console 
device, the procedure sets the device to 0. 

Exceptions 

not in SCT 
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Retrieve_software_entry 



function Retrieve_software_entry 

return KMDS_Defs . software_entry; 
pragma outerf ace {value, Retrieve software entry) 



Return Type and Value 



KMDS_Def s . sof tware_entry 

User visible software information. 



Operation 



Extracts user visible information from the SCT's software entry and returns this information in 
a record. 
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Set_system_monitorjparameters 



procedure Set_system_monitor_parameters ( 

parameters : KMDS_Def s . sm_ctrl_j?aram) ; 
pragma outerface (value, Set_system_monitor_parameters) ; 

Parameters 

parameters New System Monitor Control Parameters. 

Operation 

Sets the System Monitor parameters in the SCT's software entry. 

These parameters control System Monitor behavior during the next system warm start. 



SCT Access-15 



PRELIMINARY 



SSM Access 



Allows the caller to access System Support Module (SSM) functions. 

Security 

Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



Calls 



Blower_control 

Sends a BlwrCtl request to the default SSM. 

DC_control 

Sends a DCCt 1 request to the default SSM. DC power in the box (i.e. system 
enclosure) selected by box will be either turned on or off depending on the value 
of turn_on. 

Echo Sends an EchoChar request to the master microcontroller, which returns the 

character. 

Read_error_log 

Sends a RdErrLog request to the selected SSM. The error log from the specified 
SSM is returned. 

Read_NID 

Sends a RdNlD request to the SSM microcontroller, which then returns a Unique 
ID. 

Read_revision 

Sends a RdRe v request to the master microcontroller, which returns the revision 
level of its firmware. 

Read_SSM_config 

Sends a RdSSMCf g request to the SSM. The SSM replies with a description of its 
configuration. 

Re ad_S SM_i nput s 

Sends a Rdlnp request to the selected SSM. The raw input signals to the selected 
SSM are returned. 

Read_TOD 

Sends a RdTOD request to the SSM. The SSM replies with the value of its back-up 
Time Of Day (TOD) timer. 
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Write_LED 

Sends a Wr LED request to the default SSM. The SSM will set the mode of the 
system error LED to mode. 

Write_TOD 

Sends a WrTOD request to the SSM. 



Summary 



Warning 



This package contains procedures which allow the caller to access some of the System Support 
Module's (SSM) functions. The functions accessible by this package allow System Ad- 
ministrators, (or Diagnostic Users with System Administrator level access) to retrieve infor- 
mation from the SSM, and to test the communication path to the SSM. 

In some systems, there will be a primary and a secondary SSM. When appropriate, the 
procedures and functions in this package will have an input parameter, which allows the caller 
to send a request to a specific SSM. 

The default handling for a request is: to send it to all SSMs in the system, and return the reply 
from the primary SSM. If the primary SSM is not available, or does not respond, the secondary 
SSM's reply will be returned to the caller. 

The communication path to the SSM consists of a microcontroller (sometimes called the 
Master microcontroller), which is attached to one of the computational system's buses and the 
Serial System Bus (SSB). The microcontroller receives requests for SSM services from sys- 
tem software (e.g. this package), and transmits them across the SSB to the SSM, which acts on 
the request, and returns a reply. For more information about how the SSM hardware works see 
the hardware reference manuals. 



Misuse of these SSM functions could result in a system crash or physical damage to the system 
(e.g. overheating because the blowers were turned off). This interface should only be used by 
software and users who are aware of this possibility. 

To fully understand the consequences of calls to the procedures in this package the user must 
be familiar with the SSM hardware. 



Exceptions 



req-uest_nacked 

Raised when a request is not accepted by the SSM. 
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Declarations 



SSM select 



type SSM_select is ( 
primary, 
secondary, 
default) ; 

for SSM_select use ( 
primary => 0, 
secondary => 1, 
default => 2) ; 
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Blower control 



procedure Blower_control { 

turn_on: boolean; 

full_speed: boolean; 
select_SSM: SSM_select := default); 

Parameters 

turn_on True => Turn blower on, False => Turn blower off. 

f ull_speed True => Blower on 100%, False => Blower on 50%. 
s e le ct_S SM Selects which SSM the request will be sent to. 

Operation 

Sends a BlwrCtl request to the default SSM. 

The air blower in the system continer will be either turned on or off, and if it is turned on it 
will be set to full or half speed depending on the value of f ull_speed. 

Exceptions 

request nacked 
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DC control 



procedure DC_control ( 
turn_on: 
buffered: 
pslla: 
psllb: 
select_SSM: 
box: 



boolean; 
boolean := 
boolean := 
boolean := 
SSM select 



true; 
true; 
true; 
:= default; 



SSM_Defs .enclosure_select := SSM_Def s .main_system) 



Parameters 



turn_on 

buffered 

pslla 

psllb 

select_SSM 

box 



True => Turn power on, False => Turn power off. 

True => Control buffered power supply. 

True => Control power to PS-IIa's. 

True => Control power to PS-IIb's. 

Selects which SSM the request will be sent to. 

Selects enclosure whose power will be affected. 



Operation 



Sends a DCCt 1 request to the default SSM. DC power in the box (i.e. system enclosure) 
selected by box will be either turned on or off depending on the value of t ur n_on. 

Also, if ps Ilb_only is true then only the PS-IIb power supplies in the box will be affected. 

If the caller specifies SSM_Defs.reserved_ext for the box a System_Exceptions . bad_ 
parameter exception will be raised. 



Exceptions 

request nacked 
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Echo 

1 / 

\i 
function Echo( 

character : KMDS_Def s . seven_bit_f ield; 
select_SSM: SSM_select := default) 
return KMDS_Def s . seven_bit_f ield; 

Parameters 

character Character to be echoed. 

s e le ct_S SM Selects which SSM the request will be sent to. 

Return Type and Value 

KMDS_Def s . seven_bit_f ield 

Character echoed by master microcontroller. 

Operation 

Sends an EchoChar request to the master microcontroller, which returns the character. 
This function's returned value is the character echoed by the master microcontroller. 

Exceptions 

request nacked 
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Read_errorJog 



function Read_error_log ( 

select_SSM: SSM_select := default) 
return SSM_Def s. SSM_error_log; 

Parameters 

s e 1 e c t_S SM Selects which SSM the request will be sent to. 

Return Type and Value 

SSM_Def s . SSM_error_log 

Error log from selected SSM. 



Operation 



Sends a RdErrLog request to the selected SSM. The error log from the specified SSM is 
returned. 



Exceptions 

request nacked 
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Read NID 



/ 
function Read_NID ( \ 

select_SSM: SSM_select := default) 
return System. ordinal; 

Parameters 

se le ct_S SM Selects which SSM the request will be sent to. 

Return Type and Value 

System. ordinal 

SSM Unique ID. 

Operation 

Sends a RdNlD request to the SSM microcontroller, which then returns a Unique ID. 

Exceptions 

request nacked 
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Read revision 



function Read_re vision ( 

select_SSM: SSM_select := default) 
return System. byte_ordinal; 

Parameters 

select_SSM Selects which SSM the request will be sent to. 

Return Type and Value 

System . byte_ordinal 

Master micro firmware revision level. 



Operation 



Sends a RdRev request to the master microcontroller, which returns the revision level of its 
firmware. 



Exceptions 

request nacked 
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Read_SSM_config 

function Read_SSM_conf lg ( ( 

select_SSM: SSM_select := default) ^ 

return SSM_Def s.SSM_conf ig; 

Parameters 

s e 1 e c t _S SM Selects which SSM the request will be sent to. 

Return Type and Value 

SSM_Def s ."SSM_config 

SSM's configuration information. 



Operation 



Sends a RdSSMCf g request to the SSM. The SSM replies with a description of its configura- 
tion. 



Exceptions 

request_nacked 
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Read_SSIVHnputs 



/ function Read_SSM_inputs ( 

select_SSM: SSM_select := default) 
return SSM_Def s . SSM_inputs; 

Parameters 

s e le ct_S SM Selects which SSM the request will be sent to. 

Return Type and Value 

SSM_Def s . SSM_inputs 

Raw input signals to selected SSM. 

Operation 

\ Sends a Rdlnp request to the selected SSM. The raw input signals to the selected SSM are 

returned. 

Exceptions 

request nacked 
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Read TOD 



function Read_TOD ( ^ 

select_SSM: SSM_select := default) 
return KMDS_Defs .TOD; 

Parameters 

se le ct_S SM Selects which SSM the request will be sent to. 

Return Type and Value 

KMDS_Defs.TOD 

Back-up TOD time from SSM. 



Operation 



Sends a RdTOD request to the SSM. The SSM replies with the value of its back-up Time Of 
Day (TOD) timer. 



Exceptions 

request nacked 
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Write LED 



procedure Write_LED( 

LED_ID : KMDS_Def s . two_bit_f ield; 

mode: SSM_Defs .LED_modes) ; 

Parameters 

LED_ID Selects the LED whose mode will be altered. 

mo de Selected LED ' s ne w mode. 



Operation 



Sends a WrLED request to the default SSM. The SSM will set the mode of the system error 
LED to mode. 

Either the System Error LED or the Online Replacement LED can be selected. 



Exceptions 

request nacked 
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Write_TOD 

procedure Write_TOD ( 

time: KMDS_Defs .TOD) ; 

Parameters 

t ime Time of day to send to backup TOD timers. 

Operation 

Sends a WrTOD request to the SSM. 
time is the data portion of this request 

Exceptions 

request_nacked 
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SSM Defs 



Defines types and constants used to interface to the SSM. 

Security 

Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 

Summary 

The System Support Module provides the following functions: 

• Watchdog timer 

• Time-of-day backup timer 

• Power supply control and monitoring 

• Control panel interface 

• Unique system identification number (UID) 

• Link to the serial system bus 

• Generalization of intialization events 

• Environmental monitoring. 
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Declarations 



SSM_requests 



type SSM_requests is ( 
echo_char, 
read_rev, 
gen_OR_int, 
read_status, 
read_conf ig, 
sys_init, 
DC_cntrl, 
blower_cntrl, 
read_err_log, 
read_inputs, 
load_env_timer, 
read_TOD, 
write_TOD, 
write_LED, 
write_watchdog, 
config_SSM, 
read_NID, 
send_to_MD, 
conf ig_OR__int, 
single_initO, 
single_initl, 
double_init, 
load_COM_word, 
basic, 

read_TOD_RAM, 
write_TOD_RAM, 
load_mem_init_bit) ; 

Standard messages which can be sent to or received from an SSM. 



SSMjreplies 



type SSM_replies is { 
acknowledge, 
neg_acknowledge , 
echo_char_reply, 
read_rev_reply, 
read_status_reply, 
read_config_reply, 
read_err_log_reply, 
read_inputs_reply, 
read_TOD_reply, 
read_NID_reply, 
read_TOD_RAM_rep ly , 
no_reply) ; 

SSM replies to requests. 
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unsolmsgs 



type unsol_msgs is ( 
switch_request, 
power_fail, 
environment_f ail , 
from_MD, 

external_interrupt , 
undefined, 
request_timeout) ; 

Types of unsolicited messages which can be generated by SSM. 



enclosure select 



type enclosure_select is ( 
tower_0, 
tower_l, 
tower_2, 
tower_3, 
main_system, 
reserved_ext) ; 

for enclosure_select use ( 

tower_0 => 2#000#, 

tower_l => 2#001#, 

tower_2 => 2#010#, 

tower_3 => 2#011#, 

main_system => 2#100#, 

reserved ext => 2#101#) 



Used to select the system enclosure upon which the SSM Command will act. 



watchdog_interval 



type watchdog_interval is 
record 

time_base : KMDS_Def s . two_bit_f ield; 

time_interval : KMDS_Def s . seven_bit_f ield; 
end record; 

Watchdog timer interval. 

Fields: 

time_base Values of time base are: => timer is off. 1 => 0.1 second per count. 2 

=> 1 .0 second per count 3 => undefined. 

t ime_i nt er va 1 

Number of counts in interval. 
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disable timer 



disable_timer : constant watchdog_interval := (time_base => 0, 

time_interval => 0); 

Turn off the watchdog timer. 



min timeout 



min_timeout : constant watchdog_interval := (time_base => 1, 

time_interval => 1) 

Shortest possible watchdog timeout interval (100 milliseconds). 



max timeout 



max_timeout : constant watchdog_interval := (time_base => 2, 

time_interval =>16#7F#); 

Maximum possible watchdog timeout internal (127 seconds or about 2 minutes). 



standard timeout 



standard_timeout : constant watchdog_interval := (time_base => 1, 

time_interval => 100); \ 

Standard short timeout interval. Current value of 10 seconds is arbitrary. 



ssm loc rec 



type ssm_loc_rec is ( 
ssm_container, 
ssm_tower, 
ssm_mini) ; 

for ssm_loc_rec use ( 

ssm_container => 2#000#, 

ssm_tower => 2#001#, 

ssm_mini => 2#010#) 

SSM location. 

Enumeration Literals: 

ssm_container 

SSM installed in container. 

s sm_t ower SSM installed in tower. 

ssm mini SSM installed in minibox. 
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SSMconfig 



type SSM_config is 














record 












pslla_0 




bool< 


2an; 








pslla 1 




bool< 


san; 








psllb 




bool< 


2an; 








psllb_l 




bool< 


5an; 








psllc_l 




bool< 


san; 








ssm location: 


ssm 


Loc rec; 






firmware rev: 


Syst< 


3m. byte ordinal 


; 


board_rev: 


KMDS 


_Defs 


.four bit 


field; 


board_layout : 


KMDS" 


Defs 


.three 


bit 


field 


company : 


KMDS" 


_Defs 


. one_bit_f 


ield; 


rev overf lowl : 


KMDS" 


_Defs 


.four bit 


field; 


rev overf low2 : 


KMDS" 


_Defs 


. four bit 


field; 


end record; 












for SSM config use 










record 












pslla_0 


at 





range 


. 


. 




pslla 1 


at 





range 


1 . 


. 1 




psllb 


at 





range 


2 . 


. 2 




psllb_l 


at 





range 


3 . 


. 3 




psllc 1 


at 





range 


4 . 


. 4 




ssm_location 


at 


1 


range 


. 


. 7 




firmware rev 


at 


2 


range 


. 


. 7 




board rev 


at 


3 


range 


. 


. 3 




board_layout 


at 


3 


range 


4 . 


. 6 




rev_overflowl 


at 


4 


range 


. 


. 3 




company 


at 


4 


range 


4 . 


. 4 




rev_overflow2 


at 


5 


range 


. 


. 3, 




end record; 















SSM configuration information. 



Fields: 

pslla_0 

pslla_l 

psllb_0 

psllb_l 

psllc_l 

ssm_location 

firmware_rev 

board__rev 

board_layout 

company 

rev_overflowl 

rev overflow2 



PS-IIa-0 installed. 

PS-IIa-1 installed. 

PS-IIb-0 installed. 

PS-IIb-1 installed. 

PS-nc-1 installed. 

Where SSM is installed. 

SSM firmware rev. level. 

SSM board rev. level. 

SSM board layout level. 

Company which produced SSM board. 

SSM Board revision overflow area. 

SSM Board revision overflow area. 
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LED modes 



type LED_modes is ( 
off, 
on, 
slow, 
fast) ; 

for LED_modes use ( 

off => 2#00#, 
on => 2#01#, 
slow => 2#10#, 
fast => 2#11#) 



LED modes. 

Enumeration Literals: 

off Turn the LED off. 

on Turn the LED on. 

slow Set LED to slow blink ( 1 Hz). 

fast Set LED to fast blink (5Hz). 



SSM_error_Iog 



type SSM_error_log is 
record 

parity_errors: System. byte_ordinal; 
message_retries : System. byte_ordinal; 
end record; 

for SSM_error_log use 

record 

parity_errors at range . . 7, 

message_retries at 4 range . . 7; 

end record; 



SSM error log. 

Fields: 

parity_errors 

Number of parity errors. 

message_retries 

Number of retried messages. 



SSMJnputs 



type SSM_inputs is 
record 

not_5F_A0: boolean; 

not_12F_A0: boolean; 

not_5F_Al: boolean; 

not_12F_Al : boolean; 

not_DCF_B0: boolean; 

not BDCF: boolean; 
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not BA F: 




boolean, 








not MAN BUT: 


boolean, 








not OLR BUT: 


boolean, 








not RST BUT: 


boolean, 








not TEST: 


boolean, 








not AIR F: 


boolean, 








not ERR: 


boolean, 








not DCF Bl: 


boolean, 








FLT EX0~ 




boolean 








FLT EX1 




boolean 








FLT EX2 




boolean 








FLT EX3 




boolean 








not TF I : 


boolean 








not TF CC: 


boole 


an 








not_TF_P : 


boolean 








not CPS .AO 




boolean 








not_CPS_Al 




boolean 








not CPS BO 




boolean 








not CPS Bl 




boolean 








not_5BF_C: 


boolean 








not CDCF: 


boolean 








TOWER: 


boolean 








not UPS: 


boole 


an 








not BAX F: 


boolean 








not TF A: 


boolean 








MINIBOX: 


boolean 








DCON_S : 


boolean 








not ACF: 


boolean 








ACFX: 


boolean 








not EXT INTO 


boolean 








not EXT INT1 


boolean 








not EXT INT2 


boolean 








not EXT INT3 


boolean 








not EXT INT4 


boolean 








not EXT INT5 


boolean, 








not EXT INT6 


boolean, 








not_EXT_INT7 


boolean, 








end record; 












for SSM_inputs 


use 










record 












not 5F AO 


at 





range 


. 


. 


not 12F AO 


at 





range 


1 . 


. 1 


not 5F Al 


at 





range 


2 . 


. 2 


not_12F_Al 


at 





range 


3 . 


. 3 


not_DCF_B0 


at 





range 


4 . 


. 4 


not_BDCF 


at 





range 


5 . 


. 5 


not BA F 


at 





range 


6 . 


. 6 


not MAN BUI 


at 


1 


range 


. 


. 


not OLR BUI 


at 


1 


range 


1 . 


. 1 


not_RST_BUl 


at 


1 


range 


2 . 


. 2 


not TEST 


at 


1 


range 


3 . 


. 3 


not_AIR_F 


at 


1 


range 


4 . 


. 4 


not ERR 


at 


1 


range 


5 . 


. 5 


not DCF Bl 


at 


1 


range 


6 . 


. 6 


FLT EXO 


at 


2 


range 


. 


. 


FLT EX1 


at 


2 


range 


1 . 


. 1 


FLT EX2 


at 


2 


range 


2 . 


. 2 


FLT EX3 


at 


2 


range 


3 . 


. 3 


not TF I 


at 


2 


range 


4 . 


. 4 


not_TF CC 


at 


2 


range 


5 . 


. 5 


not TF P 


at 


2 


range 


6 . 


. 6 


not_CPS AO 


at 


3 


range 


. 


. 


not CPS Al 


at 


3 


range 


1 . 


. 1 


not CPS BO 


at 


3 


range 


2 . 


. 2 


not_CPS_Bl 


at 


3 


range 


3 . 


. 3 


not_5BF_C 


at 


3 


range 


4 . 


. 4 


not CDCF 


at 


3 


range 


5 . 


. 5 


TOWER 


at 


3 


range 


6 . 


. 6 


notJJPS 




at 


4 


range 


. 


. 
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not_BAX_F at 4 

not_TF_A at 4 

MINIBOX at 4 

DCON_S at 4 

not_ACF at 4 

ACFX at 4 

not_EXT_INTO at 5 

not_EXT_INTl at 5 

not_EXT_INT2 at 5 

not_EXT_INT3 at 5 

not_EXT_INT4 at 6 

not_EXT_INT5 at 6 

not_EXT_INT6 at 6 

not_EXT_INT7 at 6 
end record; 



range 
range 
range 
range 
range 
range 6 
range 
range 1 
range 2 
range 3 
range 
range 1 
range 2 
range 3 



Names of the SSM input signals. A not prefix indicates that the signal uses negative true 
logic. 



Fields: 

not_5F_A0 

not_12F_A0 

not_5F_Al 

not_12F_Al 

not_DCF_B0 

not_BDCF 

not_BA_F 

not_MAN_BUT 

not_OLR_BUT 

not_RST_BUT 

not_TEST 

not_AIR_F 

not_ERR 

not_DCF_Bl 

FLT_EX0 

FLT_EX1 

FLT_EX2 

FLT_EX3 

not_TF_I 

not_TF_CC 

not_TF_P 

not_CPS_A0 

not_CPS_Al 

not_CPS_B0 

not_CPS_Bl 

not 5BF C 



In minibox : not BL F 
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not_CDCF 

TOWER 

not_UPS 

not_BAX_F 

not_TF_A 

MINIBOX 

DCON_S 

not_ACF 

ACFX 

not_EXT_INTO 

not_EXT_INTl 

not_EXT_INT2 

not_EXT_INT3 

not_EXT_INT4 

not_EXT_INT5 

not_EXT_INT6 

not EXT INT7 



In minibox: not_RESET 
In tower: CPS CI 



OR_int_type 



type OR int_type is ( 






disable, 






on line_insert, 






turn_on_stable store, 






local_reset, 






turn_on_board) ; 






for OR int_type use { 






disable 


=> 


2#000#, 


on line insert 


=> 


2#001#, 


turn on stable store 


=> 


2#010#, 


local_reset 


=> 


2#011#, 


turn_on_board 


=> 


2#100#) 



Possible OR interrupts. 

Enumeration Literals: 

di s abl e Disable the OR interrupt. 

on_line_insert 

Use OR interrupt for on_line insertion on AP bus. 

turn_on_stable_store 

Use OR interrupt for stable store turn on. 

local_reset Use OR interrupt for local reset of board. 

t u r n_o n_bo ar d 

Use OR interrupt for board turn on after insertion. 
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board mode 



type board_mode is ( 
normal, 
lbO_active, 
lbl_active, 
default) ; 

for board_mode use ( 
normal 
lbO_active 
lbl_active 
default 



=> 2#00#, 

=> 2#01#, 

=> 2#10#, 

=> 2#11#) 



Possible mode of boards after init. 



Enumeration Literals: 

normal Follow the predicted BXU/MCU mode. 



Ib0_active 
lbl_active 
default 



Use LBO's resource, for GDP board FRC split mode. 

Use LBTs resource, for GDP board, only LB1 is functional. 

Use default mode, for GDP board FRC mode for others lbO mode. 



OR_param__rec 



type OR_param_rec ( 

select_int: OR_int_type := local_reset) is 
record 

case select_int is 

when local_reset => 
core: boolean; 
non_core: boolean; 
init_mode: board_mode; 
when others => 

null; 
end case; 
end record; 

pragma suppress (discriminant_check,OR_param_rec) 



for OR_param_rec use 
record 

select_int at 
core at 

non core at 



init_mode 
end record; 



at 






range 


. 


. 2 





range 


3 . 


. 3 





range 


4 . 


. 4 





range 


5 . 


. 6 



Fields: 

select_int 
core 

non_core 
init mode 



Possible OR interrupt configurations. 

True => all core boards pay attention. 

True => all non_core boards pay attention. 

Indicates which mode the board should come up in after init. 
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SSM_param_rec 



type SSM param rec is 










record 












box: 


enclosure se 


lect ; 






test : 


boolean; 










battery: 


boolean; 










extension: 


boolean; 










end record; 












for SSM param 


rec use 










record 












box 


at 





range 


. 


. 2 


test 


at 





range 


4 . 


. 4 


battery 


at 





range 


5 . 


. 5 


extension 


at 





range 


6 . 


. 6 


end record; 













Parameter for configure SSM command. 



Fields: 

box 
test 
battery 
extension 



Selects box which will be affected. 
If true, test mode on. 
If true, external battery connected. 
If true, container connected. 



DC cntrl rec 



type DC cntrl rec is 



record 












box: 


enclosure 


se 


lect; 






turn on: 


boolean; 










buffered: 


boolean; 










PSIIa: 


boolean; 










PSIIb: 


boolean; 










end record; 












for DC cntrl 


rec use 










record 












box 


at 





range 


. 


2 


buffered 


at 





range 


3 . 


3 


PSIIa 


at 





range 


4 . 


4 


PSIIb 


at 





range 


5 . 


5 


turn on 


at 





range 


6 . 


6 


end record 













Format of a DC power control record. 



Fields: 

box 

turn_on 
buffered 
PSIIa 



Selects box which will be affected. 
If true, turn DC power on. If false, turn DC power off. 
If true, affect source of buffered memory power. 
If true, affect PS-IIa power supplies. 
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If true, affect PS-IIb power supplies. 



blower cntrl rec 



type blower_cntrl_rec is 
record 

box: enclosure_select; 

full_speed: boolean; 

turn_on: boolean; 
end record; 



for blower cntrl 


rec use 








record 










box 


at 


range 


. 


. 2 


full_speed 


at 


range 


5 . 


. 5 


turn on 


at 


range 


6 . 


. 6 


end record; 











Format of an air blower control record. 



Fields: 

box 

full_speed 
turn on 



Selects box which will be affected. 

If true, set blower for full speed. If false, set blower for half speed. 

If true, turn blower on. If false, turn blower off. 



SSM status 



type SSM_status is 
record 

watchdog_overf low : 

DC_on : 

reset: 

AC_power_return : 

sys_init_request : 
end record; 

for SSM_status use 
record 

watchdog_overf low 

DC_on 

reset 

AC_power_return 

sys_init_request 
end record; 



boolean; 
boolean; 
boolean; 
boolean; 
boolean; 



at 





range 


. 


. 


at 





range 


1 . 


. 1 


at 





range 


2 . 


. 2 


at 





range 


3 . 


. 3 


at 





range 


4 . 


. 4 



SSM status data. 

Fields: 

watchdog_overflow 

INIT assertion due to watchdog timer. 

DC_o n INIT assertion due to DC-ON button. 

reset INIT assertion due to RESET button. 

AC_j?ower_return 

INIT assertion due to return of AC power. 
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sys_init__request 

INIT assertion due to SSM Init. request. 



NID byte 



type NID_byte is 
record 

NID_nibble : KMDS_Def s . f our_bit_f ield; 
zero : KMDS_Def s . f our_bit_f ield; 
end record; 

for NID_byte use 
record 

NID_nibble at range . . 3, 
zero at range 4 ..7, 

end record; 



Format of raw NID data byte. 

Fields: 

NlD_nibble Low four bits of byte contain NID data. 
zero High four bits are zero. 



raw NID 



type raw_NID is array (System. ordinal range 1 .. 8) of NID_byte; 
pragma pack (raw_NID) ; 

Raw NID data returned by SSM. 



raw data buffer 



type raw_data_buffer is array (System. ordinal range 1 .. 8) 
of System. byte_ordinal; 

pragma pack (raw_data_buf fer) ; 

Raw data buffer. 



requestformat 



type request_format ( 

request: SSM_requests := write_TOD) is 
record 

case request is 
when echo_char I 

send_to_MD => 
char: KMDS_Defs.seven_bit_field; 
when read_rev | 

gen_OR_int I 
read_NID | 
read_TOD | 
single initO | 
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single_initl I 
double_init | 
basic I 

read_TOD_RAM => 
null; 
when read_status | 
sys_init | 
read_err_log I 
read_inputs I 
read_config => 
box: enclosure_select; 

when DC_cntrl => 

DC: DC_cntrl_rec; 

when blower_cntrl => 

blower: blower_cntrl_rec; 
when load_env_timer => 

counter: enclosure_select; 
count : KMDS_Def s . seven_bit_f ield; 
when write_TOD I 

write_TOD_RAM => 
time: KMDS_Def s.TOD; 
when write_LED => 

LED_select : KMDS_Def s . two_bit_f ield; 
mode: LED_modes; 
when write_watchdog => 

interval: watchdog_interval; 
when config_SSM => 

SSM_param: SSM_param_rec; 
when conf ig_OR_int => 

OR_param: OR_param_rec; 
when load_COM_word => 

index: System. ordinal range . . 2; 
when load_mem_init_bit => 
set_bit: boolean; 
end case; 
end record; 

pragma suppress (discriminant_check, request_f ormat) 



for request_format use 
record 

request at range . 

char at 1 range . 

box at 1 range . 

DC at 1 range . 

blower at 1 range . 

counter at 1 range . 

count at 2 range . 

time at 1 range . 

LED_select at 1 range . 

mode at 1 range 5 . 

interval at 1 range . 

SSMjoaram at 1 range . 

OR_param at 1 range . 

index at 1 range 5 . 

setjbit at 1 range . 
end record; 



- 1, 



- 1, 



Fields: 

request 
char 
box 
DC 



Format of SSM requests with data bytes. 
Character argument. High-order bit will be forced to 0. 
Selects enclosure whose SSM will perform the request. 
DC power supply control data. 
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blower Blower control data. 

counter Selects SSM whose environment timer will be loaded. 

count Count. 

t ime Time of Day. 

LED_select Selects the LED (System Error or Online Rep OK) whose mode will be 
changed. 

mode Display mode for LED (i.e. on, off, fast blink, or slow blink). 

int erval Time before watchdog timer goes off. 

SSM_param Informs SSM about configuration. 

OR_param Configures the OR interrupt. 

index Indicates which COM word to load (i.e. 0, 1, or 2). 

set_bit If true, set Memory Initialized bit in COM word 1 . If false, clear Memory 

Initialized bit. 



reply_format 



type reply_format ( 

reply: SSM_replies := acknowledge) is 
record 

case reply is 

when echo_char_reply I 
read_rev_reply => 
char : KMDS_Def s . seven_bit_f ield; 

when read_status_reply => 

status: SSM_status; 
when read_config_reply => 

config: SSM_config; 
when read_err_log_reply => 

error_log: SSM_error_log; 
when read_inputs_reply => 

inputs: SSM__inputs; 
when read_TOD_reply | 

read_TOD_RAM_reply => 
TOD: KMDS_Defs.TOD; 

when read_NID_reply => 

NID: raw_NID; 

when others => 

raw_data: raw_data_buf fer; 
end case; 
end record; 

pragma suppress (discriminant_check, reply_f ormat) 

for reply format use 



record 


















reply 


at 





range 


. 


7 , 








char 


at 


1 


range 


. 


7 , 








status 


at 


1 


range 


. 


7, 








config 


at 


1 


range 


. 


6 


* 


8 - 


- 1 


error_log 


at 


1 


range 


. 


6 


• 


8 - 


- 1 


inputs 


at 


1 


range 


. 


7 


* 


8 - 


- 1 


TOD 


at 


1 


range 


. 


8 


* 


8 - 


- 1 


NID 


at 


1 


range 


. 


8 


* 


8 - 


- 1 


raw_data 


at 


1 


range 


. 


8 


* 


8 - 


- 1 


end record; 
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unsol_msg_format 



type unsol_msg_format ( 

msg: unsol_msgs := po 
record 

primary: bool 

source: encl 

case msg is 

when switch_request 
manual_request : 
online_replacement 
DC_off : 
test: 

when power_fail => 
AC_fail_other_PSII 
AC_ret_other_PSIIc 
UPS_on: 
UPS_off : 

sys_battery_f ail : 
ext_battery_f ail : 
buf_5v_bus_f ail : 
PSIIaO_5v_fail: 
PSIIaO_12v_fail: 
PSIIal_5v_fail: 
PSIIal_12v_fail: 
PSIIbO_fail: 
PSIIbl_fail: 
buf_5v_supply_fail 
AC_fail: 
AC_returns : 

when environment_fai 
PSIIc_temp: 
cage_temp_air : 
periph_temp_air : 
air_intake_temp : 
blower: 
mini_0 : 
mini_l : 
mini_2 : 
mini_3 : 

when from_MD => 
char : 

when external_interr 
ext_intO : 
ext_intl : 
ext_int2 : 
ext_int3 : 
ext_int4 : 
ext_int5 : 
ext_int6: 
ext_int7 : 

when others => 
null; 
end case; 
end record; 



wer_fail) is 

ean; 

osure select; 



=> 



boolean; 
boolean; 
boolean; 
boolean; 

boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 

boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 



System . byt e_ordinal , 
upt => 

boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 
boolean; 



1 => 



pragma suppress (discriminant_check,unsol_msg_format) 



r unsol msg format use 






record 








msg 


at 


range 





primary 


at 4 


range 





source 


at 1 


range 





manual request 




at 2 




online replacement 


at 2 




DC off 




at 2 




test 




at 2 




AC fail other 


PSIIc 


at 2 





. . 7, 
. . 7, 
. . 7, 
range 
range 1 
range 2 
range 3 
range 
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AC_ret_other_PSIIc 
UPS_on 
UPS_off 

sys_battery_fail 
ext_battery_fail 
buf_5v_bus_fail 
PSIIaO_5v_fail 
PSIIaO_12v_fail 
PSIIal_5v_fail 
PSIIal_12v_fail 
PSIIbO_fail 
PSIIbl_fail 
buf_5v_supply_fail 
AC_fail 
AC_returns 
PSIIc_temp 
cage_temp_air 
periph_temp_air 
air_intake_temp 
blower 
mini_0 
mini_l 
mini_2 
mini_3 
char 
ext_intO 
ext_intl 
ext_int2 
ext_int3 
ext_int4 
ext_int5 
ext_int6 
ext_int7 
end record; 



at 


2 


at 


2 


at 


2 


at 


2 


at 


2 


at 


2 


at 


3 


at 


3 


at 


3 


at 


3 


at 


3 


at 


3 


at 


3 


at 


4 


at 


4 


at 


2 


at 


2 


at 


2 


at 


2 


at 


2 


at 


3 


at 


3 


at 


3 


at 


3 


at 


2 


at 


2 


at 


2 


at 


2 


at 


2 


at 


3 


at 


3 


at 


3 


at 


3 



range 1 . 

range 2 . 

range 3 . 

range 4 . 

range 5 . 

range 6 . 

range . 

range 1 . 

range 2 . 

range 3 . 

range 4 . 

range 5 . 

range 6 . 

range . 

range 1 . 

range . 

range 1 . 

range 2 . 

range 3 . 

range 4 . 

range . 

range 1 . 

range 2 . 

range 3 . 

range . 

range . 

range 1 . 

range 2 . 

range 3 . 

range . 

range 1 . 

range 2 . 

range 3 . 



Fields: 

ms g Format of data in an unsolicited message. 

primary If true, this message came from primary SSM. If false, this message came 

from secondary SSM. 

source System box (i.e. enclosure) which caused this message. 

manual_request 

Manual mode requested. 

online_replacement 

Online replacement requested. 

DC_o f f Turn off DC power request. 

test Test request. 

AC_fail_other_PSIIc 

AC power to the other PS-IIc failed. 

AC_r et_other_P S 1 1 c 

AC power returned on the other PS-IIc. 

UP S_on Container's UPS is on. 

UPS_off Container's UPS is off. 

sys_battery_fail 

Battery failure in a container. 

ext_battery_fail 

External battery failure. 
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buf_5v__bus_f ail 

Buffered +5VDC bus failure in a container. 

PSIIaO_5v_fail 

PS-IIa-0 +5VDC failure in a container. 

PSIIaO_12v_fail 

PS-IIa-0 12VDC failure in a container. 

PSIIal_5v_fail 

PS-IIa-1 +5VDC failure in a container. 

PSIIal_12v_fail 

PS-IIa-1 12VDC failure in a container. 



PSIIbO_fail 
PSIIbl fail 



PS-IIb-0 failure in a container. 
PS-IIb-1 failure in a container. 



buf_5v_supply_fail 

Buffered +5VDC supply failure in a container. 

AC_f ail AC input power fail. 

AC_r e t ur n s AC input power returns after failure. 

P S 1 1 c_t emp PS-IIc internal temperature fault in a container. 

c a ge_t emp_a i r 

Temp/Airflow fault in a container's cardcage. 

periph_temp_air 

Temp/Airflow fault in a container's peripherals. 

air_intake_temp 

Ambient air intake temp, fault in a container. 

Blower fault 

Fault in extension minibox 0. 

Fault in extension minibox 1. 

Fault in extension minibox 2. 

Fault in extension minibox 3. 



blower 

mini_0 

mini__l 

mini_2 

mini_3 

char 

ext_int0 

ext__intl 

ext_int2 

ext_int3 

ext_int4 

ext_int5 

ext_int6 

ext int7 



External interrupt is active. 
External interrupt 1 is active. 
External interrupt 2 is active. 
External interrupt 3 is active. 
External interrupt 4 is active. 
External interrupt 5 is active. 
External interrupt 6 is active. 
External interrupt 7 is active. 
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unsol_msg_VA 



type unsol_msg_VA is access unsol_msg_format , 
pragma ACCESS_KIND (unsol_msg_VA, VIRTUAL); 



invalid slot number 



in valid_slot_n umber: constant KMDS_Def s. slot_number := 0, 

SCT_Mgt indicates an empty slot by setting the slot number to zero. 



SCTSSMwarning 



SCT SSM warning: 



constant := 2; 



SCT fault type (fjype) code for SSM Daemon warnings. 



no_warning 



no warning: 



constant := 0; 



timeout 



timeout : 



constant := 1, 



send not started 



send not started: 



constant 



overlappedrequests 



overlapped_requests: constant := 3, 
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illegal_control_char 



illegal_control_char : constant := 4 



unexpected__reply 



unexpected reply: constant := 5, 



bad_parity 



bad parity: 



constant := 6, 



extraneous etx 



extraneous etx: 



constant := 7; 



unexpected_exception 



unexpected exception: constant := 8, 



extraneous nack 



extraneous nack: 



constant := 9, 



system_error_LED 



system error LED: constant KMDS Defs.two bit field := 2#01#; 



online_rep_LED 



online_rep_LED: constant KMDS_Def s. two_bit_f ield := 2#10#; 

Constants defined for quick check for standard replies. 
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ack_reply 



ack_reply: constant reply_format (reply => acknowledge) :=( 

reply => acknowledge, 
raw data => (others => 0)); 



nack_reply 



nack_reply: constant reply_format (reply => neg_acknowledge) :=( 

reply => neg_acknowledge, 
raw_data => (others => 0)); 

Encodings of SSM control characters. Note: The control characters used to comunicate with 
the SSM are NOT ASCII. They have a special unique encoding. 



stx 



stx: 



constant System. byte_ordinal := 2#10000000#; 



etx 



etx: 



constant System. byte_ordinal := 2#11111000#, 



ack 



ack: 



constant System. byte_ordinal := 2#11111001#, 



nack 



nack; 



constant System.byte_ordinal := 2#11111010#, 



rdy 



rdy: 



constant System.byte_ordinal := 2#11111011i 
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sync 



sync 



constant System. byte ordinal := 2#11111100#; 



control char format 



type control_char_format is 
record 

control: boolean; 

c_bits: KMDS_Defs.four_bit_field; 

mjoits: " KMDS_Def s. three_bit_field; 
end record; 



for control char 


format use 




record 






control at 


range 7 . 


. 7 


c bits at 


range 3 . 


. 6 


m bits at 


range . 


. 2 


end record; 







Used to break down control bytes into meaningful bit fields. 



not stx 



not_stx: constant KMDS_Defs . four_bit_f ield :- 2#1111#, 

The c_bits have this value for all control characters except stx. 



etx m bits 



etx m bits: constant KMDS Defs. three bit field := 2#000#; 



ack m bits 



ack m bits: constant KMDS Defs. three bit field := 2#001#; 



nack m bits 



nack m bits: constant KMDS Defs. three bit field := 2#010#, 
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rdy_m_bits 



rdy_m_bits: constant KMDS_Def s . three_bit_f ield := 2#011#, 

Constants used to build Designate Master request. 



des master code 



des master_code: constant System. byte_ordinal := 16#08#, 



des master des dbl 



des_master_des_dbl : constant System.byte_ordinal := 2#01000000#, 



des master undes dbl 



des_master_undes_dbl : constant System.byte_ordinal := 2#00000000# J 

Encodings stx byte of unsolicited messages. 



switch_request_code 



switch_request code: constant System. byte ordinal := 16#48#; 



power_fail_code 



power_fail_code: constant System. byte_ordinal := 16#4 9#; 



environment fail code 



environment_fail_code: constant System. byte_ordinal := 16#4A#j 



from MD code 



f rom_MD_code : constant System. byte_ordinal := 16#4B#j 
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ext_interrupt_code : constant System.byte_ordinal := 16#4C#, 

Memory Addresses for accessing SSM Master Micros 



primary__address 



primary_address: constant System. ordinal := 16#2000_0000#; 



secondary_address 



secondary_address: constant System. ordinal := 16#2004_0000#, 



primary JBXU_match 



primary BXU match: 



constant KMDS_Def s . fourteen_bit_f ield 
primary_address / (2**18) ; 



secondary^BXUjnatch 



secondary_BXU_match: constant KMDS_Def s. fourteen_bit_f ield 

secondary address / (2**18) ; 



BXU mask 



BXU mask: 



constant KMDS Defs . fourteen bit field := 16#3FFF#, 



core status address 



core_status_address: constant System. ordinal := 16#00200000#, 



core data address 



core_data_address: constant System. ordinal := 16#00400000#, 
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datadisp 



data disp: 



constant := 0, 



Word displacement 



statusdisp 



status disp: 



constant := 4 



Word displacement 



echo_char_req_code 



echo char req code: 



constant System. byte ordinal := 16#09#, 



read_rev_req_code 



read rev req_code: 



constant System. byte ordinal := 16#0A#, 



gen_OR_int_code 



gen OR int code: 



constant System. byte_ordinal := 16#0B#, 



read_status_req_code 



read status req code 



constant System. byte ordinal := 16#18#, 



read_config_req_code 



read_conf ig_req_code : 



constant System. byte ordinal := 16#19#, 



sys_init_req_code 



sys_init_req_code : 



constant System. byte_ordinal := 16#1A#, 
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DC_cntrI_req_code 



DC cntrl req code: 



constant System. byte_ordinal := 16#1B#; 



blower_cntrl_req_code 



blower cntrl req_code : constant System. byte_ordinal := 16#1C#, 



read_err_log_req_code 



read err log req code: constant System. byte_ordinal := 16#1D#, 



read_inpiits_req_code 



read_inputs_req_code : 



constant System. byte_ordinal := 16#1E# ; 



load_env_timer_req_code 



load_env_timer_req_code: constant System. byte_ordinal := 16#1F#, 



read_TOD_req_code 



read_TOD_req code : 



constant System. byte ordinal := 16#20#, 



write_TOD_req_code 



write TOD req code: 



constant System. byte_ordinal := 16#21#, 



writeJLED_req_code 



write_LED_req_code : 



constant System. byte ordinal := 16#22#, 



SSM Defs-26 



PRELIMINARY 



write_watchdog_req_code 



write_watchdog req_code: constant System. byte_ordinal := 16#23#, 



config_SSM_req_code 



conf ig_SSM_req_code : 



constant System. byte_ordinal := 16#24#, 



read_NID_req_code 



read NID req code: 



constant System. byte_ordinal := 16#25#, 



read_TOD_RAM_req_code 



read_TOD_RAM_req_code : constant System. byte_ordinal := 16#26#, 



write_TOD_RAM_req_code 



write_TOD_RAM_req_code : constant System. byte_ordinal := 16#274 



send_to_MD_req_code 



send to MD req code: 



constant System. byte ordinal := 16#30i 



config_OR__int_code 



conf ig_OR_int_code : 



constant System. byte ordinal := 16#41#, 



single_initO_req_code 



single_initO_req_code: constant System. byte ordinal := 16#42#, 
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single_initl_req_code 



single initl req_code: constant System. byte_ordinal := 16#4 3#; 



double_init_req_code 



double init req_code : 



constant System. byte_ordinal := 16#44#, 



load_COM_word_req_code 



load_COM_word_req_code: constant System. byte_ordinal := 16#45#; 



basic_req_code 



basic req code: 



constant System. byte_ordinal := 16#4 6#; 



load mem init bit code 



load_mem_init_bit_code: constant System. byte_ordinal := 16#4 7#; 



xmit index 



subtype xmit_index is System. byte_ordinal range 1 .. 11; 

Index into transmission buffers. 

Maximum size of a SSM message is 1 1 bytes (1 stx byte + 8 data bytes + 1 parity byte + 1 etx 
byte). 



xmit buffer 



type xmit_buffer is array (xmit_index) of System. byte_ordinal; 
pragma pack (xmit_buf fer) ; 

Transmit buffer array. 
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xmit buffer VA 



type xmit_buf fer_VA is access xmit__buffer; 
pragma ACCESS_KIND (xmit_buffer_VA, VIRTUAL) 



reply_stx_codes 



reply stx codes: constant array (SSM replies) of System. byte_ordinal 



acknowledge 


=> 


16#00#, 


neg acknowledge 


=> 


16#01#, 


echo char reply 


=> 


16#10#, 


read rev reply 


=> 


16#11#, 


read status reply 


=> 


16#28#, 


read config reply 


=> 


16#29#, 


read err log reply 


=> 


16#2B#, 


read inputs reply 


=> 


16#2C#, 


read TOD reply 


=> 


16#2A#, 


read NID reply 


=> 


16#2D#, 


read_TOD_RAM_reply 


=> 


16#2E#) ; 



request_bit_mask 



type reguest_bit_mask is array ( 

xmit_index range 1 . . 8) of System. byte_ordinal; 

pragma pack (request bit mask); 



request_data_record 



type request_data_record is 
record 

data_length: System.byte_ordinal; 

reply: SSM_replies; 

stx_code: System.byte_ordinal; 

mask: request_bit_mask; 
end record; 



for request data record use 



record 






data length 


at 





reply 


at 


1 


stx code 


at 


2 


mask 


at 


3 


end record; 







range 
range 
range 
range 



8-1, 



Request data record. 



Fields: 

data_length 

reply 

stx code 



Number of data bytes in request. 
Expected reply to this request. 
Start of TeXt byte for this request. 
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mask 



Mask used to force reserved data bits to zero. 



request_data_table 



request_data_table 
(echo char 



read rev 



gen OR int 



read status 



read config 



sys init 



DC cntrl 



blower cntrl 



read err log 



read_inputs 



constant array (SSM_ 
=> (data_length 
reply 
stx_code 

mask 

=> (data_length 
reply 
stx_code 
mask 

=> (data_length 
reply 
stx_code 

mask 

=> (data_length 
reply 
stx_code 

mask 

=> (data_length 
reply 
stx_code 
mask 

=> (data_length 
reply 
stx_code 
mask 

=> (data_length 
reply 
stx_code 
mask 

=> (data_length 
reply 
stx_code 
mask 

=> (data_length 
reply 
stx_code 

mask 

=> (data_length 
reply 
stx_code 
mask 



load_env_timer => (data_length 

reply 
stx_code 

mask 



read TOD 



write TOD 



=> (data_length 
reply 
stx_code 
mask 

=> (data_length 
reply 



requests) of request_data_record := 

' => 1, 
=> echo_char_reply, 
=> stx + echo_char_req_code, 
=> (16#7F#, others => 0)), 

=> 0, 

=> read_rev_reply, 

=> stx + read_rev_req_code, 

=> (others => 0) ) , 

=> 0, 

=> acknowledge, 

=> stx + gen_OR_int_code, 

=> (others => 0) ) , 

=> 1, 

=> read_status_reply, 

=> stx + read_status_req_code, 

=> (16#07#, others => 0)), 

=> 1, 

=> read_config_reply, 

=> stx + read_conf ig_req_code, 

=> (16#07#, others => 0)), 

=> 1, 

=> no_reply, 

=> stx + sys_init_req_code, 

=> (16#07#, others => 0)), 

=> 1, 

=> acknowledge, 

=> stx + DC_cntrl_req_code, 

=> (16#7F#, others => 0)), 

=> 1, 

=> acknowledge, 

=> stx + blower_cntrl_req_code, 

=> (16#67#, others => 0)), 

=> 1, 

=> read_err_log_reply, 

=> stx + read_err_log_req_code, 

=> (16#07#, others => 0)), 

=> 1, 

=> read_inputs_reply, 

=> stx + read_inputs_req_code, 

=> (16#07#, others => 0)), 

=> 2, 

=> acknowledge, 

=> stx + load_env_timer_req_code, 

=> (16#07#, 16#7F#, others => 0)), 

=> 0, 

=> read_T0D_reply, 

=> stx + read_T0D_req_code, 

=> (others => 0) ) , 

=> 8, 

=> acknowledge, 
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stx_code 
mask 



> 


stx + write 


_TOD_ 


req_ 


code, 


> 


(16#7F#, 
16#3F#, 
16#3F#, 
16#1F#, 
16#07# f 
16#1F#, 
16#0F#, 
16#7F#)), 









write LED 



=> (data_length 
reply 
stx_code 

mask 



=> 1, 

■•> acknowledge, 

=> stx + write_LED_req_code, 

=> (16#63#, others => 0)), 



write watchdog 



=> (data_length 
reply 
stx_code 

mask 



=> 2, 

=> acknowledge, 

-> stx + write_watchdog_req_code, 

=> (16#03#, 16#7F#, others => 0)) 



config_SSM 



=> (data_length 
reply 
stx_code 
mask 



=> 1, 

-> acknowledge, 

=> stx + conf ig_SSM_req_code, 

o> (16#77#, others => 0)), 



read NID 



=> (data_length 
reply 
stx_code 

mask 



=> 0, 

=> read_NID_reply, 

=> stx + read_NID_req_code, 

=> (others => 0) ) , 



send to MD 



=> (data_length 
reply 
stx_code 

mask 



=> 1, 

--> acknowledge, 

=> stx + send_to_MD_req_code, 

=> (16#7F#, others => 0)), 



config OR int 



=> (data_length 
reply 
stx_code 
mask 



=> 1, 

=> acknowledge, 

=> stx + conf ig_OR_int_code, 

=> (16#7F#, others => 0)), 



single_init0 



=> (data_length 
reply 
stx_code 
mask 



=> 0, 

=> acknowledge, 

=> stx + single_initO_req_code, 

=> (others => 0) ) , 



single initl 



=> (data_length 
reply 
stx_code 
mask 



» 0, 

=> acknowledge, 

: > stx + single_initl_req_code, 

=> (others => 0) ) , 



double init 



=> (data_length 
reply 
stx_code 

mask 



=> 0, 

=> acknowledge, 

=> stx + double_init_req_code, 

=> (others => 0) ) , 



load COM word 



=> (data_length 
reply 
stx_code 

mask 



=> 1, 

=> acknowledge, 

=> stx + load_COM_word_req_code, 

=> (16#60#, others => 0)), 



basic 



=> (data_length 
reply 
stx_code 

mask 



=> 0, 

=> acknowledge, 

=> stx + basic_req_code, 

=> (others => 0) ) , 



read TOD RAM 



=> (data_length 
reply 
stx_code 
mask 



=> 0, 

=> read_TOD_RAM_reply, 

=> stx + read_TOD_RAM_req_code, 

=> (others => 0) ) , 
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write TOD RAM => 



(data_length 


=> 


8, 




reply 


=> 


acknowledge, 




stx code 


=> 


stx + write TOD RAM req code, 




mask 


=> 


<16#7F#, 


/ 






16#3F#, 


I 






16#3F#, 








16#1F#, 








16#07#, 








16#1F#, 








16#0F#, 








16#7F#) ), 





load_mem_init_bit => (data_length => 1, 

reply => acknowledge, 

stx_code => stx + load_mem_init_bit_code, 

mask => (16#01#, others => ) ) ) ; 



pragma external; 
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Test_Support 



This package allows the user to access KMDS's built-in diagnostic functions. In general, 
differences in implementation are masked by the test procedures provided here. For example: 
Test_memory_controller can be used to test any type of memory controller in any type of 
system, and the caller does not have to be aware of what type of memory controller is being 
tested. The subtest_result record, which is returned by all of the test procedures, has 
been generalized to simplify things. Some of the parameters do not make sense in all of the 
tests. It is up to the caller to determine what to do with the results and isolate the failure to a 
specific part of the module. The test procedures will run different sets of subtests depending 
on the type of module under test and the type of system. 



Security 



Calls 



Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



GDP_diag_driver 

This is a template for a GDP Diagnostics Driver procedure. 

Map_j?rocessor_ID_to_CP 

This function maps a processor ID to a CP object. 

Set_board_LED 

Attempts to turn the LED on the board in the given slot number on or off as 
indicated by LED_on. 

Set_diagnostic_mode 

This procedure sets the system to be brought up in diagnostics mode at its next 
boot It also brings all of the online memory board entries offline with in the 
System Configuration Table. The functional status of the stable store is not al- 
tered. 

Set__normal_mode 

This procedure sets the system to be brought up in normal mode at its next boot. It 
also brings all of the offline memory board entries online with in the System Con- 
figuration Table. The functional status of the stable store and the memory 
modules with status of faulty, or offline_or_faulty is not altered. 



Test BXU 



This test makes extensive use testability features built into the VLSI component in 
order to test AP bus register set, timer, FRC circuits, parity checking logic, error 
reporting mechanisms, and the cache. These functions will be tested in the logical 
BXU identified by logical ID and bus ID. 
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Te s t_CP Test_CP initiates execution of the CP's built-in tests. These tests are the Internal 
and External Self-Tests and the IOS Test, passed indicates whether the CP 
passed the tests. The subtests array indicates whether the individual subtests 
passed. If pa s s ed is true than all of the subtests passed. 

Test_GDP 

Test_GDP runs the given diagnostics routines on the specified GDP. In general 
these subroutines should address those areas of the GDP that are not covered by its 
self-test, t est_pr oc s is the virtual address to the list of test procedure to run on 
the selected GDP. The GDP is identified through the given logical_lD and 
processor_select. If test_procs is null then a standard test will be run. 
. timeout specifies the maximum time (in milliseconds) for the test procedures to 
run on the GDP. 

Test_memory 

Built-in test features are used to test the memory in the range between 
starting_displacement and ending_displacement . The "ending_ 
displacement " is the address of the memory location which was tested most 
recently. IfTest_memory failed, it is the address of the failed word. The output 
parameter passed is TRUE, if the test succeeded, and FALSE, if the test failed. 
All displacements are byte displacements, however the two least significant bits 
are always masked to zero, so testing must start and end on word boundaries. 

Test_memory_cont roller 

This procedure tests the ECC generation of the memory controllers in the memory 
module. This is done by loading data with bad ECC into memory (using special 
memory controller hooks), and then reading that data back via a normal memory 
access. Normal, memory error reporting will be disabled during this test. Since 
some memory modules can have more than one memory controller (one for each 
system bus), and BXU based memory controllers are actually on a local bus, the 
out parameter controller will indicate which memory controller failed. 

Test_private_memory 

The procedure tests the external RAM used by BXU caches. This test may only be 
run when the system is in the diagnostic mode of operation, module is the ID of 
the module (GDP or 10) which contains the cache RAM to be tested. If this test 
finds a failure f aulty_disp will indicate which cache RAM is faulty. If no 
failures are found passed will be True. 

Virtual ADR 



Exceptions 



unresponsive_target 

Raised when an attempt to deactivate or activate a hardware component (i.e. a 
processor) has failed. 

diag_target_unknown 

Raised when the necessary information pertaining to the hardware component un- 
der test cannot be retrieved. 

wrong_target_type 

Raised when a test is run on an incorrect component. For example running GDP 
diagnostics on memory. 
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invalidate st_range 

Raised when caller specifies a test range other than the test allows to be specified 
(e.g., Test_Memory_controller allows only 'bcl' or 'all_tests' 

invalid_memory_range 

Raised when caller specifies a starting displacement bigger than the ending dis- 
placement, or when either exceeds the size of the memory module 

target_not_of f line 

Raised when a (memory) module does not have offline status before testing. 

CP_not_in_pool 

Raised by Map_processor_ID_to_CP when CP_Mgt's pool of CPs does not con- 
tain a CP with the requested processor ID. 

inter leaved_partner_not_found 

Raised when testing a memory module requires an inter- leaved partner memory 
module that cannot be found. 
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Declarations 



possible_sub_resuIts 



type possible_sub_results is (passed, 

failed, 

not_run, 

running) 



Enumeration Literals: 

passed The subtest was executed correctly. 



failed 

not_run 

running 



The subtest was executed incorrectly. 
The subtest was not run (or does not exist). 
Subtest is currently running. 



test type 



type test_type is (memory, 
GDP, 
CP, 
MCU, 
BXU); 



a ok 



a_ok: constant integer := 0, 

Reserved for use when there is no error. 



unknown error 



unknown_error: constant integer := 1; 

Signals an undefined error. 



bad access 



bad_access: constant integer := -1; 

Used for errors in accessing the registers or locations. 



Test_Support-4 



PRELIMINARY 



could not run test 



could_not_run_test : constant integer := 2; 

Indicates that the test code tried to run the subtest but could not complete the test for some 
reason. This is probably due to a lack of resources due to a conflict with another test procedure. 



memoryjrecord 



type memory_record is 



record 

data_word: 

tag: 

ecc_check : 

spare : 

reserved: 
end record; 



System . ordinal ; 
KMDSJDefs .one_bit_f ield; 
KMDS_Def s . seven_bit_f ield; 
KMDS_Defs .one_bit_f ield; 
KMDS Defs. seven bit field; 



for memory record use 



record 

data_word 

tag 

ecc_check 

spare 

reserved 
end record; 



at 
at 
at 
at 
at 



range . .31; 
range 32 . .32 
range 33 . .39 
range 40 . .40 
range 41 . .47 



Fields: 

data_word 

tag 

ecc_check 

spare 

reserved 



The actual 32-bit data word. 

The GDP-defined tag bit 

The check bits generated by ECC 

The spare bit provided by memory. 

Only used to make the container size an even multiple of bytes. 



memory_controller_desc 



type memory_controller_desc is (none, 

local_bus, 
sys_bus0, 
sys busl) ; 



Enumeration Literals: 

none None of the memory controllers failed the test 

local_bus 

sys_bus0 

sys_busl 



The memory controller on local bus failed (private memory) 
The MCU connected to system bus failed. 
The MCU connected to system bus 1 failed. 
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memory_test_types 



type memory_test_types is (data_bus_ripple, 

address_bus_ripple, 

march, 

refresh) ; 



Enumeration Literals: 

data_bus_ripple 

Ripple test of data bus. 

address_bus_ripple 

Ripple test of address bus. 

ma r c h Marching test both up and down. 

refresh Array refresh test. 



memory_controller_subtests 



type memory_controller_subtests is (all_tests, 

bcl, 

memory_array_test, 
partial_word_update, 
ECC correct detect) ; 



Enumeration Literals: 

a 1 l_t e s t s Performs all Memory_controller_subtests 

be 1 Test MCU/BXU AP bus interface 

memo r y_ar r ay_t e s t 

pa r t i a l_wo r d_updat e 

ECC_correct__detect 

This type describes the subtests that can be done on private memory 



(GDP/GENIO cache/local memory) 



privatememorysubtests 



type private_memory_subtests is (nibble, 

stuck at) ; 



Enumeration Literals: 

nibble Checks 4 bit wide static RAMs. 

stuck at Checks for bits stuck a or 1. 
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type test_step is (all_bits, 
data, 
ecc, 
tag) ; 



Enumeration Literals: 

all_bit s Perform test on data, ecc, tag bits 

data Perform test on data portion of memory array only 

ecc Perform test on ecc portion of memory array only 

tag Perform test on tag bits only 



pattern_miscompare 



pattern_miscompare : constant integer := 2; 

Used for errors detected by comparing expected and actual values. 



patternfault 



pattern_fault: constant integer := 3, 

Used for the errors detected by the HW. 



parity_fault 



parity_fault : constant integer := 4; 

Used for tag/spare errors detected by BXU_mem hardware. 



ECC detect fault 



ECC_detect_f ault : constant integer := 5; 

Used for incorrect detecting of pattern errors (i.e., should have been detected by hardware, but 
wasn't). 
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ECC_parity_detect_fault 



ECC_parity_detect_fault : constant integer := 6; 

Used for incorrect detecting of tag/spare errors (i.e., should have been detected by hardware, 
but wasn't). 



array_not_usable 



array__not_^usable: constant integer := -2; 

Used by controller tests when the memory array won't work for the controller test. 



bi word 



type bi_word is 
record 

wordO : System . ordinal ; 

wordl: System. ordinal; 
end record; 

for bi_word use 
record 

wordO at range .. 31, 
wordl at 4 range . . 31, 
end record; 



datatypes 



type data_types is (one_byte, 

two_bytes, 
four_bytes, 
eight_bytes, 
sixteen_bytes, 
mem record) ; 



Enumeration Literals: 

one_byte One byte data, 

t wo_by t e s Two byte data, 

f our_by t e s Four byte data, 
e i ght_by t e s Eight byte data. 
sixteen_bytes 



Sixteen byte data. 

mem_record Define a record which hold up to the largest (sixteen_bytes, AKA quad, 
word) of the memory data types. 
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pattern_rep 



type pattern_rep is 
.record 

any_data_type: System_Def s .quad_word; 
memory_record: Test_Support . memory_record; 
end record; 



for pattern_rep use 
record 

any_data_type 
memory_record 
end record; 



at 
at 



range 
16 range 



127, 
47, 



Fields: 

any_dat a_t ype 

memo r y_r e c o r d 



Type has space for the largest data (quad_word). It can also have smaller 
types. Used by memory controller test. 

The 41 -bit memory record. This is most commonly used by memory tests. 



mem subtest result 



:ype mem_subtest_result (bcl_test: boolean := false) is 
record 

sub_result: possible_sub_results := not_run; 
failure_code: integer := 0; 
case bcl_test is 
when false => 

last_displacement : System. ordinal; 
type_of_data: data_ types := mem_record; 
expected: pattern_rep := (any_data_type => 



memory_record => 



actual: 



pattern_rep := (any_data_type => 



memory_record => 



(wordO => 0, 
wordl => 0, 
word2 => 0, 
word3 => 0) , 

(data_word => 0, 
tag => 0, 
ecc_check => 0, 
spare => 0, 
reserved => 0) 

(wordO => 0, 
wordl => 0, 
word2 => 0, 
word3 => 0) , 

(data_word => 0, 
tag => 0, 
ecc check => 0, 



spare 
reserved 



=> 0, 
=> 0) 



expected_syndrome : 
actual_syndrome : 
controller: 
when true => 

component_status : 
end case; 
end record; 



KMDS_Def s . seven_bit_f ield 
KMDS_Def s . seven_bit_f ield 
memory_controller_desc; 

FT_Testing.test_results; 



:= 0, 
;= 0, 



pragma suppress (discriminant_check,mem_subtest_result) ; 

for mem_subtest_result use 
record 
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bcl_test at range 

sub_result at range 1 

failure_code at 1 range 

last_displacement at 5 range 
type_of_data at 9 range 

expected at 10 range 

actual at 32 range 

expected_syndrome at 5 4 range 
actual_syndrome at 55 range 
controller at 56 range 

component_status at 5 range 
end record; 




7 
31 
31 
7 
175 
175 
7 
7 
7 
63; 



Fields: 

bcl_test 
sub result 



Indicates results of this subtest. 



f ailure_code Indicates why test failed. Values for this field are assigned by the subtests 
so the same value may have different meanings for different subtests. 
True if all memory controllers passed. 

last_displacement 

Address of last word tested 

t ype_o f _dat a This identifies which type of data. 

expe ct ed Data expected to be read from array. 

actual Actual data from array that was read read. 

expect ed_syndrome 

The ECC syndrome bits expected. 

actual_syndrome 

The ECC syndrome bits received. 

controller When testing controller, contains ID of controller. When testing 
BXU/MCU, contains ID of the bus agents. 

component_status 



mem_array_results 



type mem_array_results is array (memory_test_types) of mem_subtest_result; 
pragma pack (mem_array_results) ; 



mem ctlr results 



type mem_ctlr_re suits is array (memory_controller_subtests) of mem_subtest 

pragma pack (mem ctlr results); 
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private_mem_results 



type private_mem_results is array (private_memory_subtests) of mem_subtest_re 
pragma pack (private_mem_results) ; 



max number subtests 



max number subtests: constant := 12; 



Each GDP diagnostics routine may write data pertaining to the results of it's particular test to a 
diagnosis buffer. The following is the size of such an array. 



module_diag_buffer_size 



module_diag_buf f er_size : constant System. ordinal := 8; 

Maximum number of processes that are allowed to be spawned by a diagnostic process, it is an 
arbitrary value. 



max_number_pf_processes 



max_number_of_processes: constant System. ordinal := 50; 

The default maximum time (in milliseconds) to wait for a set of given GDP tests to complete. 
Tests that do not return in this time frame indicate a faulty (or dead) GDP. This value is used 
by procedure Test_GDP. Users of this routine may wish to specify a different timeout period 
as necessary. 



GDP_test_timeout_period 



GDP_test_timeout_period: constant System. ordinal := 1000; 

The structure of the buffer used to disclose farther diagnosis of the GDP under test by the test 
routine. Developers of the GDP diagnostics routine may wish to use such a structure to report 
more meaningful messages by their routine. 



diagnosisbuffer 



type diagnosis_buffer is array (1 .. module_diag_buf fer_size) of System. byte 
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GDP subtest result 



type GDP_subtest_resu.lt (bcl_test: boolean := false) is 
record 

sub_result : possible_sub_results := not_run; 

failure_code: integer := 0; 

completed: boolean := false; 

test_report: diagnosis_buf fer; 
end record; 

for GDP_subtest_result use 
record 

sub_result at range .. 7; 

failure_code at 1 range . . 31; 

completed at 5 range . . 31; 

test_report at 9 range . . 63; 
end record; 



Fields: 

bcl_test 

sub_r e suit Indicates results of this subtest. 

f ailur e_code Indicates why test failed. Values for this field are assigned by the subtests 
so the same value may have different meanings for different subtests. 
True if all memory controllers passed. 

comp le t e d Signals that the current GDP diagnostics routine is completed, when it is 

set to true. 

t e st_r eport Optional value. May be used by user's GDP test routines to write diag- 
nostic messages (i.e. It may be used to write certain error messages). 



subtest index 



subtype subtest index is System. ordinal range 1 .. max number subtests; 



GDP subtest results 



type GDP_subtest_results is array (subtest_index) of GDP_subtest_result; 
pragma pack (GDP subtest results); 



GDP_diag_routine_list 



type GDP_diag_routine_list is array (subtest_index) of System. subprogram_type 
pragma pack (GDP_diag routine list); 
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diag_proc_list 



type diag_proc_list is 
record 

num_tests: subtest_index; 
diag_modules : GDP_diag_routine_list, 
end record; 



Fields: 

num_t e s t s Number of test routine pointers in diag_modules. 

diag_modules List of pointers to GDP diagnostics routines. 



diag_proc_list_VA 



type diag_proc_list_VA is access diag_proc_list; 
pragma access_kind (diag_proc_list_VA, virtual); 



diag_status_buffer 



type diag_status_buffer is 
record 

done: boolean : = false; 

results: GDP_subtest_results, 
end record; 



Fields: 



done Status of the entire GDP diagnostics routine. When set to true, it indicates 

that all of the given test routines have completed running on the desig- 
nated GDP (normally or abnormally). 

results List of GDP diagnostics test results. 



process_AD_Iist 



type process_AD_list is array (1 . . max_number_of_processes) of Process_Mgt_T 

The following data structure is used by the callers to Test_GDP to define the necessary data for 
this module. Using this information Test_GDP will locate the processor under test, sets it up, 
and runs the given diagnostics routines on it. 
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processor_under_test_data 



type processor_under_test_data is 



record 

cardcage_ID: 

slot : 

psor : 

master: 
end record; 



KMDS_Defs.cardcage_ID_rep := KMDS_Def s . sys, 
KMDS_Defs.slot_number := 0; 
KMDS_Defs.one_bit_field := 0; 
boolean := true; 



Fields: 

cardcage_ID 

slot 

psor 
master 



ID of the cardcage containing the processor board, that holds the GDP to 
be diagnosed. 

Slot number of the processor board in the given cardcage. Note that value 
of zero indicates an invalid slot number. 

The GDP to be tested. 

Test the master GDP when set to true. 



BXU subtests 



type BXU_subtests is ( 
FRC, 
parity, 
error_report, 
timeout, 
LERL, 

cache_directory, 
IO^prefetch, 
extend) ; 

This first group of subtests only require access to the BXU from the AP-Bus side. These tests 
make up the BXU BCL test. 



Enumeration Literals: 

FRC 

parity 

error_report 

timeout 

LERL 



ijtsrt selt checking rK,C circuitSo 

Check parity detection circuits. 

Check error reporting circuits. 

Bus bad access timeout. 

Check Local Error Report Line (LERL). 

cache_directory 

Check internal cache directory. 

I0_jpr e fetch Check 10 prefetcher (10 boards only). 

extend Check additional BXU logical units. I.e. IAC message support, Memory 

support, and etc. 
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BXU subtest result 



type BXU_subtest_result (logical_failure : boolean := false) is 
record 

sub_result: possible_sub_results := not_run; 
failure_code: integer := 0; 
case logical_failure is 
when true => 

logical_detail : System. ordinal; 
when false => 

component_status : FT_Testing . test_results; 
end case; 
end record; 

pragma suppress (discriminant_check,BXU_subtest_result) ; 

for BXU_subtest_result use 
record 

logical_failure at range .. 0; 

sub_result at range 1 . . 7; 

failure_code at 1 range . . 31 

logical_detail at 5 range . . 31 

component_status at 5 range . . 63 
end record; 



Fields: 

logical_failure 

sub_r e suit Indicates results of this subtest. 

f ailur e_code Indicates why test failed. Values for this field are assigned by the subtests 
so the same value may have different meanings for different subtests. 
True if all memory controllers passed. 

logical_detail 

component status 



BXU subtest results 



type BXU_subtest_results is array <BXU_subtests) of BXU_subtest_result; 
pragma pack (BXU subtest results); 



CP subtests 



type CP_subtests is ( 
self_test, 
IOS) ; 



Enumeration Literals: 

s e 1 f _t est CP's built-in internal/external self-tests. 

IOS CP's built-in IOS Test. 
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other subtest result 



type other_subtest_result is 
record 

sub_result: possible_sub_results := not_run; 

failure_code : integer := 0; 
end record; 

for other_subtest_result use 
record 

sub_result at range 1 .. 7; 

failure_code at 1 range . . 31; 
end record; 



Fields: 

sub_r e suit Indicates results of this subtest. 

f ailure_code Indicates why test failed. Values for this field are assigned by the subtests 
so the same value may have different meanings for different subtests. 
True if all memory controllers passed. 



CP subtest results 



type CP_subtest_results is array (CP_subtests) of other_subtest_result; 
pragma pack(CP subtest results); 



GDP_diag_driver_type 



subtype GDP_diag_driver_type is System. subprogran^type, 
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GDP__diag_driver 



procedure GDP_diag_driver ( 

subprogram : GDP_diag_driver_type ; 
result: out GDP subtest result); 



Parameters 

subprogram 



result 



Result of the GDP diagnostics. 



Operation 



This is a template for a GDP Diagnostics Driver procedure. 

procedure <Name> (result: out GDP_subtest_result); 

pragma subprogram_value(GDP_diag_driver, <Name>); 

where <Name> is the user's GDP diagnostic routine procedure, result is the result of the 
test just run. The actual diagnostics routine is reponsible for updating it's fields. 

The pragma indicates that <Name> provides an alternate body to the GDP_diag_driver 
template defined above, result specifies the results of the test that was just run on the GDP 
under test. 
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Map__processorJD_to_CP 



function Map_processor_ID_to_CP ( 

psor_id: KMDS_Def s.processor_ID) 
return CP Mgt.CP AD; 



Parameters 

psor_id 

Return Type and Value 

CP_Mgt . CP_AD 

Operation 

This function maps a processor ID to a CP object. 



Exceptions 



System_Exceptions . bad_parameter 
This is raised if processor ID is null. 
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Set board LED 



procedure Set_board_LED ( 

slot: KMDS_Defs . slot_number; 
LED_on: boolean := false); 

Parameters 

s lot The slot number in the given cardcage that the board resides on. 

LED_on Signal to turn the LED on the subject board on (when true), or off (when 



false). 



Operation 



Attempts to turn the LED on the board in the given slot number on or off as indicated by LED_ 
on. 
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Set__diagnostic_mode 



procedure Set_diagnostic_mode; 



Operation 



This procedure sets the system to be brought up in diagnostics mode at its next boot. It also 
brings all of the online memory board entries offline with in the System Configuration Table. 
The functional status of the stable store is not altered. 
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Set normal mode 



procedure Set normal_mode; 



Operation 



This procedure sets the system to be brought up in normal mode at its next boot. It also brings 
all of the offline memory board entries online with in the System Configuration Table. The 
functional status of the stable store and the memory modules with status of faulty, or offline_ 
or_faulty is not altered. 



Test_Support-21 



PRELIMINARY 



Test BXU 



procedure Test_BXU ( 

logical_ID : KMDS_Def s . logical_ID_rep; 

bus_ID: KMDS_Defs.VLSI_locations; 

passed: out boolean; 

subtests: out BXU_subtest_re suits; 

BCL only: boolean := false); 



Parameters 



logical_ID Logical ID of target logical BXU. 

bu s_lD System Bus BXU is attached to. 

passed If true, than all subtests were passed. 

subt e s t s Array with results of the subtests. 

BCL_only If true, only run the BXU BCL subtests. 

Operation 

This test makes extensive use testability features built into the VLSI component in order to test 
AP bus register set, timer, FRC circuits, parity checking logic, error reporting mechanisms, and 
the cache. These functions will be tested in the logical BXU identified by logical ID and 
bus_ID. 

If the parameter BCL_only is set to true, then only subtests which do not need to access the 
BXU from the local bus side will be executed. 

If the system is not in Diagnostic mode then only the BCL tests can be executed. If the system 
is in Diagnostic mode then all of the tests can be run. 

If pas sed is true then all of the subtests run on the logical BXU passed. Otherwise, (i.e. 
passed is false) one or more of the subtests failed. 

Exceptions 

FT_Testing . cannot_run_test 
SCT_Access .reserved_by_others 
SCT Access. not in SCT 
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Test CP 



procedure Test_CP ( 

logical_ID: KMDS_Def s. logical_ID_rep; 

passed: out boolean; 

subtests: out CP_subtest_results; 

psor: KMDS_Defs.psor select := KMDS Defs.psor 0) 



Parameters 

logical_ID 
passed 
subtests 
psor 



Logical ID of module containing target CP. 
If true, than all subtests were passed. 
Array with results of the subtests. 
Processor in module to be tested. 



Operation 



Test_CP initiates execution of the CP's built-in tests. These tests are the Internal and External 
Self-Tests and the IOS Test, passed indicates whether the CP passed the tests. The 
subtests array indicates whether the individual subtests passed. If passed is true than all 
of the subtests passed. 



Exceptions 



diag_target_unknown 
unresponsive_target 
wrong_target_type 
SCT Access. not in SCT 
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Test GDP 



c 

procedure Test_GDP ( ■ H 

GDP_data : processor_under_test_data; 
passed: out boolean; 
status: out diag_status_buffer; 
test_procs: diag_proc_list_VA := null; 
timeout: System. ordinal := GDP_test_timeout_period) ; 

Parameters 

GDP_data Data used to identify and locate the processor to be tested. 

passed If true, then the GDP has passed all of the subtests. 

st at u s Status buffer with results of the subtests. 

t e st_pr o c s List of pointers to diagnostics procedures to run on the selected processor. 
It is to be prepared by the users of Test_GDP. 

timeout The maximum time period needed by a set of GDP diagnostics routines 

(given through test_procs) to execute on the GDP under test. ^ 

Operation 

Test_GDP runs the given diagnostics routines on the specified GDP. In general these sub- 
routines should address those areas of the GDP that are not covered by its self-test. test_ 
procs is the virtual address to the list of test procedure to run on the selected GDP. The GDP 
is identified through the given logical_ID andprocessor_select. If test_procs 
is null then a standard test will be run. timeout specifies the maximum time (in 
milliseconds) for the test procedures to run on the GDP. 

If the output parameter pa s s ed is TRUE, the test succeeded, if it is FALSE the test failed. In 
either case, the array subtests will contain details about which subtests passed or failed. If 
passed is true than all of the subtests passed. 

Some diagnostics routines may crash the system or inactivate the GDP under test. Thus it 

should be exttemely important to the users of this procedure to make sure the system is 

prepared for such a possibility (specially in a single processor system). / 

Exceptions 

diag_target_unknown 
unresponsive_target 
SCT_Access . not_in_SCT 
SCT_Access .reserved_by_others 



Warning 
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Test_jnemory 



procedure Test_memory( 
slot : 

selected_test : 
step: 

starting_displacement : 
ending_displacement : 
num_errors : 
test_result : 
passed : 



KMDS_Def s . slot_number; 

memory_test_types; 

test_step; 

System . ordinal ; 

System . ordinal ; 
in out System. ordinal; 

out mem_subtest_result; 
out boolean) ; 



Parameters 

slot Slot number of memory module to be tested. 

selected_test 

Run this memory test. 

s t ep selects memory region to be tested 

starting_displacement 

Beginning displacement to start test. Default of zero means absolute low 
address. 

ending_displacement 

Final displacement of test Default of zero means absolute high address. 



num_errors 

test_result 
passed 



(in) The maximum number of errors to detect before returning, (out) The 
number of errors actuall detected. 

Record with results of the test. 

True if memory module passes. 



Operation 



Built-in test features are used to test the memory in the range between start ing_ 
displacement and ending_disp la cement . The "ending_displacement " is the ad- 
dress of the memory location which was tested most recently. If Test_memory failed, it is the 
address of the failed word. The output parameter passed is TRUE, if the test succeeded, and 
FALSE, if the test failed. All displacements are byte displacements, however the two least 
significant bits are always masked to zero, so testing must start and end on word boundaries. 



Exceptions 



unresponsive_target 
wrong_target_type 
SCT Access. not in SCT 
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Test_memory_controller 



procedure Test_memory_controller ( 

slot: KMDS_Defs . slot_number; 

selected_test : Memory_controller_subtests; 
test_results : out mem_ctlr_re suits; 
passed: out boolean); 

Parameters 

slot Slot number of memory module to be tested. 

s elect ed^_t est 

Run this controller test. 

test_results Array with results of subtests. 

passed True if all memory controllers passed. 

Operation 

This procedure tests the ECC generation of the memory controllers in the memory module. 
This is done by loading data with bad ECC into memory (using special memory controller 
hooks), and then reading that data back via a normal memory access. Normal, memory error 
reporting will be disabled during this test. Since some memory modules can have more than 
one memory controller (one for each system bus), and BXU based memory controllers are 
actually on a local bus, the out parameter controller will indicate which memory con- 
troller failed. 

Note: If a failure is detected in the first memory controller tested, the module's second 
memory controller will not be tested. 

Note: Before this procedure calls the code to actually test a BXU- based memory controller, it 
first calls some BXU tests to test the memory module's BXU and AP-Bus interface. 

Exceptions 

wrong__target_type 
unresponsive_target 
SCT Access. not in SCT 
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Testjprivate_memory 



procedure Test_private_memory ( 

logical_ID : KMDS_Def s . logical_ID_rep; 

passed: out boolean; 

subtests: out private_mem_results) ; 

Parameters 

logical_lD ID of module containing memory to be tested. 
passed If True, then memory passed all tests, 

subt e s t s Array with results of the subtests. 

Operation 

The procedure tests the external RAM used by BXU caches. This test may only be run when 
the system is in the diagnostic mode of operation, module is the ID of the module (GDP or 
10) which contains the cache RAM to be tested. If this test finds a failure f aulty_disp will 
indicate which cache RAM is faulty. If no failures are found passed will be True. 

Exceptions 

FT_Testing . cannot_run_test 
SCT_Access . reserved_by_others 
SCT Access. not in SCT 
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Virtual ADR 



function Virtual_ADR ( 

s: System. address) 
return diag_j?roc_list__VA; 

Parameters 

s Source value, of type System, address. 

Return Type and Value 

diag_proc_list_VA 

Result type. 

Operation 

Changes an expression's Ada type. 

Notes 

No runtime code is generated. 
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FTS Admin 



Contains administrative operations for a File Transfer Service (FTS), including defining 
remote entities, changing service parameters, and retrieving service information. 



Security 



Calls 



Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



Change_service_params 

Changes some parameters of the active service. 

Def ine_account 

Creates an account, which is allowed to be used by the specified users (name, 
location). 

Disable_local_entity 

Disables one or all local entities; subsequent connection requests are rejected. 

Enable_local_entity 

Enables one or all local entities; new connection requests can be processed through 
the entities. 

Force_activity_state 

Sets the desired state for the activity identified by the request identifier. 

Get_account_info 

Gets information about a given account 

Ge t_ac count_name s 

Gets the names of all accounts. 

Get_activity_descriptions 

Gets descriptions of the current activities (transfers) within the service. 

Get_local_entity_info 

Get local entity's parameters, status, and statistics. 

Get_local_entity__titles 

Gets the titles of all local entities. 
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Get_remote_entity_info 

Gets the system definition record for a remote entity. 

I 
Get_remote_ent it y_name s 

Gets the local names of all remote entities. 

Get_service__info 

Gets service parameters and statistics. 

Get_transf er__inf o 

Gets descriptions of the current activities within the service and information about 
all current transfer requests. 

Register_remote_entity 

Registers a remote entity within the service. 

Switch_remote_entity V 

Enables or disables a remote entity for local users. 



Summary 



FTS allows the local system to exchange files with registered remote systems. An FTS con- 
sists of one or more local entities, some registered remote entities, and some remote user 
accounts. One or more transfers {activities) may be in progress, or enqueued. 



Administering the FTS 



Some parameters of the service may be changed dynamically by calling Change_service_ 
params. Other parameters may be changed after stopping the service (see the Configure 
utility). 

Get_service_info 

Gets information about the FTS itself, including both parameters and 
status. 

Local Entities 

Files are transferred through local entities. Local entities are identified by 
title. Currently, only one local entity is supported by FTS. There are 
several calls to manage local entities: 

Enable_local_entity and Disable_local_entity 

Enables or disables one or all local entities. Either the initiating or the 
responding parts or both may enabled or disabled. 

Get_local_entity_titles 

Gets a list of all local entities' titles (names). 

Get_local_entity_info 

Gets information about a local entity, given the entity's title. There are 
three items gotten: the local entity's parameters, and both its initiating and 
responding parts' statuses and statistics. 
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Remote Entities 

Remote entities are the local system's view of remote systems. A remote 
system may have several remote entities in it; each entity is treated 
separately. 

Register_remote_entity 

Registers a remote entity with the local FTS. The remote entity's name, 
address, title, type (BiiN or non-BiiN), and other parameters may be set. 
The parameters are read by calling Get_remote_entity_inf o . 

Switch__remote_entity 

Enables or disables a remote entity for local users. 

Get_r emot e_e nt it y_name s 

Gets a list of the registered remote entities' names. 

Get_remote_entity_info 

Given a remote entity's name, gets its status and parameters. 

File Transfers 

File transfers (activities) occur as a result of transfer requests from the 
manage . transfer utility or the FTS_Transf er package's 
procedural interface. 

Get_activity_descriptions 

Gets a list of activity (transfer) description records, including the as- 
sociated local and remote entities, the transfer state, and the activity and 
transfer request IDs. 

Get_transfer_info 

Gets the same information as Get_activity_descriptions, but 
also includes specific transfer information (last operation, local and remote 
filenames, transfer parameters, log file if any, and so forth). 

Accounts 

An account is used for access control for remote users. An account has a 
name and contains a list of allowed remote users' names and locations; 
these remote users, at the allowed locations, can transfer files to and from 
the local system. An account can also include a local login name for the 
remote user, a home (base) directory, and passwords for the local or public 
login. 

Def ine_account 

Defines one account's passwords and parameters, including a list of al- 
lowed user names and locations. 

Get_account_names 

Gets a list of the current accounts' names. 

Get_account_info 

Given an account name, gets a list of its users' names and locations, as 
well as the account's local login name, local directory, and its passwords. 
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If a remote user uses an unknown (undefined) account, and the FTS parameter FTS_ 
Conf ig_Def s . service_params_t . re ject_unknown_users is false, there is no 
further protection. The unknown remote user can access any destination account where the 
destination user's protection set includes the system ID. 
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Declarations 



desired_activity_state_t 



type desired_activity_state_t is ( 
suspended, 
resume, 
aborted, 
process) ; 

Parameter to Force_activity_state. 

Enumeration Literals: 

suspended Activity is suspended until ares ume . 

re sume Resume a suspended activity, 

ab o r t e d Abort an activity being processed. 

process Process the activity as soon as possible. 
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Change__service__params 



procedure Change_service_params < 

service: FTS_Config_Defs.service_AD_t; 
params: FTS Conf ig_Def s. service_params t) ; 



Parameters 



service 
params 



FTS service, with control rights. 
New service parameters. 



Operation 



Changes some parameters of the active service. 

For a description of the parameters see FTS_Conf ig_Def s . service_params_t 

Only those parameters for which the service need not be stopped can be changed: 

• f inished_requests_deadline 

• low_cost_time 

• re ject_anonymous_users 

• re ject_unauthorized_users 

• reject_unknown_users 

• suspended_deadline 

• timed_queuing_enabled 

• timed_requests_of f set 

• timeout_deadline 

• trace level 
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Define account 



procedure Def ine_account ( 

service: FTS_Conf ig_Def s. service_AD_t; 

account name: System_Def s. text; 

users: ~~ FTS_Conf ig_Def s . identif ications_t; 

local_login: System_Def s . text := System_Def s . null_text; 

public_jpassword: System_Def s. text := System_Def s.null_text; 

implicit_password: System_Def s. text := System_Defs.null_text; 

home_dir: System_Def s. text := System_Def s . null_text) ; 

Parameters 

service FTS service, with control rights . 

account_name Account name. 

If an account with the same name exists already, the existing account 
definition is replaced by the new definition. 

users User names and locations allowed to use this account. If users .name is 

null, all names will match. If user . location is null, all locations will 
match. 

local_login Optional. Local login name. If System_Def s . null_text (default), 
the local login name is the account's name. 

public_j?as sword 

Optional. Public password to be matched by remote users, rather than the 
account's password. If System_Def s . null_text (default), only the 
local account's password must be matched. 

implicit_pas sword 

Optional. Password that is supplied for the local login. 

home_dir Optional. Directory subtree to be accessible when using this account. 

Operation 

Creates an account, which is allowed to be used by the specified users (name, location). 

The remote users allowed to use this account are specified by name and location. The loca- 
tions associated with the user names must be registered as remote entities. 

Exceptions 

FTS_Conf ig_Def s . string_too__long 
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DisableJocal_entity 



procedure Disable_local_entity { \| 

service : FTS_Conf ig_Def s . service_AD_t ; 

title: System_Defs. text := System_Def s.null_text; 

:= true; 
:= true; 
:= true; 



initiating_part : boolean 
responding_part : boolean 
wait until idle: boolean 



max_seconds_to_wait : System. ordinal := 3600; 
abort_connections: boolean := false); 

Parameters 

service FTS service, with control rights. 

title Optional. Local entity's title. If System_Def s . rmll_text (default), 

all local entities are disabled. 

initiating_part 

Optional. If true (default), the initiating part of the local entity is disabled. 

responding_j?art 

Optional. If true (default), the responding part of the local entity is dis- 
abled. 

wait_unt il_idle 

Optional. If true (default), the local entity will not be disabled until it is 
idle. If false, the entity will be disabled immediately. 

max_seconds_to_wait 

Optional. Number of seconds to wait before disabling the entity. 

abort_connections 

Optional. If true, active connections through this entity are aborted. If 
false (default), the currently active connections will be completed nor- 
mally. 

Operation 

Disables one or all local entities; subsequent connection requests are rejected. 

Either the initiating (sending) part, or the responding (receiving) part, or both parts of the 
entity(s) may be disabled. 



Exceptions 



FTS_Conf ig_Def s . unknown_entity 
title is unknown. 

FTS_Conf ig_Def s . string_too_long 

title is longer than the maximum name size. 
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Enable_local__entity 



procedure Enable_local_entity ( 

service : FTS_Conf ig_Def s . service_AD_t ; 

title: System_Def s. text := System_Def s.null_text; 

initiating_j?art : boolean := true; 

responding_part : boolean := true); 

Parameters 

service FTS service, with control rights. 

title Optional. Local entity's title. If System_Defs .null_text (default), 

all local entities are enabled. 

initiating_part 

Optional. If true (default), the initiating part of the local entity is enabled. 

re sponding_part 

Optional. If true (default), the responding part of the local entity is en- 
abled. 

Operation 

Enables one or all local entities; new connection requests can be processed through the entities. 

Either the initiating (sending) part, or the responding (receiving) part, or both parts of the 
entity(s) may be enabled. 

Exceptions 

FTS_Conf ig_Def s . unknown_entity 
FTS_Conf ig_Def s . string_too_long 
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Force_activity_state 



procedure Force_activity_state ( 

service: FTS_Conf ig_Def s. service_AD_t; 
request_id: System. ordinal; 
desired_state: desired_activity_state__t) ; 

Parameters 

service FTS service, with control rights. 

request_id Request identification, from a Get_activity_descriptions call. 

desired_state 

Desired activity state: 

suspended A batched or timed batch activity is suspended until a 

resume. 

r e sume Activity processing is resumed if it was su sp ended. 

aborted If the activity is still queued it is marked as aborted 

and will never be processed. If the activity is already 
processed, the connection will be aborted. 

proces s The activity is forced to process as soon as possible. 

Operation 

Sets the desired state for the activity identified by the request identifier. 



Exceptions 



System_Def s .bad_parameter 

request_id is unknown. 

FTS_Conf ig_Def s . state_invalid 

The activity is already aborted or terminated, or resume was requested without a 
previous suspend, or suspend was requested for an active transfer. 
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Get account info 



\ 

J procedure Get_account_inf o ( 

service : FTS_Conf ig_Def s . service_AD_t ; 

account_name : System_Def s. text ; 

users: out FTS_Conf ig_Def s . identif ications_t ; 

local_login: out System_Def s. text ; 

public_password: out System_Def s. text ; 

implicit_j?assword: out System_Defs. text; 

home_dir: out System_Def s. text) ; 

Parameters 

service FTS service, with control rights. 

ac count_name Local account's name. 

users Variable that receives a list of the users allowed to use the account. 

local_login Variable that receives the account's local login name, if any. 

) publicjpas sword 

Variable that receives the account's public password, if any. 

implicit_pas sword 

Variable that receives the account's implicit password, if any. 

home_dir Variable that receives the account's home directory, if any. 

Operation 

Gets information about a given account. 

The returned users . length field indicates the total number of user identifications. 

The caller should check if the returned users . length field is greater than users . max_ 
length. If so, only those identifications which fit in the provided array are returned; re- 
allocate an array with max_length >= users . length and repeat the call. 

Similarly, for the four returned text records, the returned text . length field indicates the 
length of each text. The caller should check if any of the returned text . length fields are 
greater than text . max_length. If so, only the characters which fit in the text are returned; 
re-allocate a text record with max_length >= t ext . length and repeat the call. 



Exceptions 



FTS_Conf ig_Def s .unknown_ac count 
The account does not exist. 

FTS_Conf ig_Def s . string_too_long 



FTS Admin-11 



PRELIMINARY 



Get account names 



procedure Get_account_names ( ^ 

service : FTS_Conf ig_Def s . service_AD_t ; 
names: out System_Def s. string_list) ; 

Parameters 

service FTS service, with control rights. 

name s Variable that receives a list of account names. 

Operation 

Gets the names of all accounts. 

The returned names . count field indicates the total number of accounts. 

The caller should check if the returned name s . length field is greater than name s . max_ ( 
length. If so, only those names which fit in the string list are returned; re-allocate a string 
list record with max_length >= name s . length and repeat the call. 
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Get__activity_descriptions 



J procedure Get_activity_descriptions ( 

service: FTS_Config_Defs.service_AD_t; 
activities: out FTS_Config_Defs .activities_t) ; 

Parameters 

service FTS service, with control rights. 

activities Variable that receives a list of activities (transfer requests). 

Operation 

Gets descriptions of the current activities (transfers) within the service. 

The returned activities . length field indicates the total number of activity descriptions. 

) The caller should check if the returned activities . length field is greater than 

activities . max_length. If so, only those activity descriptions which fit in the 
provided array are returned; re-allocate an array with max_length >= act ivit ies 
. length and repeat the call. 
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Get_local_entity_info 



procedure Get_local_entity_inf o ( ^ 

service : FTS_Conf ig_Def s . service_AD_t; 

title: System_Defs .text; 

info: out FTS_Conf ig_Defs .entity_params_t ; 

istatus: out FTS_Conf ig_Defs .status_t; 

rstatus: out FTS_Config_Defs .status_t; 
reset_statistics : boolean := false); 

Parameters 

service FTS service, with control rights. 

title Entity ' s title. 

info Variable that receives the entity's definition. 

istatus Variable that receives the status and statistics of the entity's initiating part. 

rstatus Variable that receives the status and statistics of the entity's responding 

part. 

reset_statistics 

If true, statistics are reset. 

Operation 

Get local entity's parameters, status, and statistics. 



Exceptions 



FTS_Conf ig_Def s . unknown_entity 

title is not a defined local entity. 

FTS_Conf ig_Def s . string_too_long 
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GetJocaLentity_titles 



procedure Get_local_entity_titles ( 

service : FTS_Conf ig_Def s . service_AD_t ; 
titles: out System_Def s. string_list) ; 

Parameters 

service FTS service, with control rights. 

titles Variable that receives a list of local entity titles . 

Operation 

Gets the titles of all local entities. 

The returned titles . count field indicates the total number of entities. 

The caller should check if the returned titles . length field is greater than tit les 
. max_lengt h. If so, only those titles which fit in the string list are returned; re-allocate a 
string list record with max_length >= titles .length and repeat the call. 
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Get_remote__entity_Jnfo 



procedure Get_remote_entity_info { ^ 

service : FTS_Conf ig_Def s . service_AD_t ; 
name: System_Def s. text; 
info: out FTS_Conf ig_Def s.system_rec_t) ; 

Parameters 

service FTS service, with control rights. 

name Remote entity's local name. 

info Variable that receives the entity ' s definition. 

Operation 

Gets the system definition record for a remote entity. 



Exceptions 



FTS_Conf ig_Def s . unknown_entity 

name is not a registered remote entity. 

FTS_Conf ig_Def s . string_too_long 
name is too long. 
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Get_remote_entity_names 



procedure Get_remote_entity_names ( 

service : FTS_Conf ig_Def s . service_AD_t ; 
names: out System_Def s. string_list) ; 

Parameters 

service FTS service, with control rights . 

name s Variable that receives a list of remote entities ' names. 

Operation 

Gets the local names of all remote entities. 

The returned names . count field indicates the total number of remote entities. 

The caller should check if the returned names . length field is greater than names . max_ 
length. If so, only those names which fit in the string list are returned; re-allocate a string 
list record with max_length >= names . length and repeat the call. 
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Get service info 



procedure Get_service_info ( 

service: FTS_Config_Defs . service_AD_t; 

info: out FTS_Config_Defs . service_params_t; 

status: out FTS_Config_Defs . status_t; 

reset_statistics : boolean := false); 

Parameters 

service FTS service, with control rights. 

info Variable that receives the service parameters. 

status Variable that receives the status and statistics of the service. 

reset_statistics 

Optional. If true, statistics are reset for the service and for all local en- 
tities. 

Operation 

Gets service parameters and statistics. 
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Get transfer info 



procedure Get_transf er_inf o ( 

service : FTS_Conf ig_Def s . service_AD_t; 
activities: out FTS_Config_Def s ,activities_t; 
infos: out FTS Config Def s . transfer_inf os t) ; 



Parameters 



service 

activities 

infos 



FTS service, with control rights. 

Variable that receives a list of activities. 

Variable that receives a list of transfer information records. 



Operation 



Gets descriptions of the current activities within the service and information about all current 
transfer requests. 

The returned activities . length and infos . length fields indicate the total number 
of activity descriptions and transfers. 

The caller should check if either of the returned x . length fields is greater than x . max_ 
length. If so, only those records which fit in the provided array are returned; re-allocate an 
array with max_length >= x . length and repeat the call. 
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Register_remote_entity 



procedure Register_remote_entity ( 

service : FTS_Conf ig_Def s . service_AD_t ; 

name: System_Def s . text; 

object_id: System_Def s. text; 

transport_address : System_Def s . text; 
session_selector : System_Def s . text 
presentation_selector : System_Def s . text 
title: System_Def s . text 

:= true; 



= System_Def s . null_text; 
= System_Def s.null_text; 
= System Defs.null text; 



alien: boolean 

time_out_deadline : integer 
virtual_f ilename_spec: boolean 



2; 

false) 



Parameters 

service FTS service, with control rights. 

name Remote entity's local name. 

ob j e c t_i d Numeric form of the object identifier for the remote entity. 

transport_address 

Transport service part of the remote entity's presentation address. 

session_selector 

Optional. Session service part of the presentation address. 

present at ion_select or 

Optional. Presentation service part of the presentation address. 

title Optional. Remote entity's title. If System_Defs .null_text 

(default), name is used. 

alien Optional. If true (default), the remote entity is on an alien (non-BiiN) 

system. 

time_out_deadline 

Optional. Number of minutes to wait after a request before retry or abort. 

virtual_f ilename_spec 

Optional. If true, remote filenames must be specified in the virtual files- 
tore convention. If false (default), remote filenames must be specified in 
the convention of the remote system. 

Operation 

Registers a remote entity within the service. 
The remote entity is initially enabled. 

The presentation address of the remote entity is composed of: 

transport address must be provided (and which is in turn composed of network address and 
TSAP endpoint). 

session selector may be provided. 

presentation selector 

may be provided. 

The object ID, address, and selectors are specified as a sequence of numbers (decimal byte 
values) separated by periods, as 47.1.0.101 
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Exceptions 

FTS_Conf ig_Def s . string_too_long 

System_Exceptions .bad_parameter 

The syntax of the number string is wrong. Either a component is missing, or too 
many components are contained, or a component has an invalid value. 
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Switch_remote_entity 



procedure Switch_remote_entity ( 

service: FTS_Conf ig_Defs .service_AD_t; 

name: System_Defs .text; 

enable: boolean; 

previously_enabled: out boolean); 

Parameters 

service FTS service, with control rights. 

name Registered remote entity's local name. 

enable If true, the remote entity is enabled; else it is disabled. 

previous ly_enabled 

Variable that receives true if the remote entity was enabled before this 
call; false otherwise. 

Operation 

Enables or disables a remote entity for local users. 

If a remote entity is disabled, it cannot be addressed through FTS. 



Exceptions 



FTS_Conf ig_Def s . unknown_entity 

name does not designate a registered remote entity. 
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FTS_Config_Defs 



Defines types, objects, and exceptions used for the administration of the File Transfer Service 
(FTS). 



Security 



Access to this package is restricted to callers carrying a privileged ID. See your System 
Administrator for access. 



Summary 



This package defines service and entity objects and their parameters and status records. 
Remote system objects, parameters, and remote user identifications are also defined. 

These definitions are used by the FTS_Admin package. A status record (transf er_inf o 
t) from the FTS_Transf er package is used to declare an array of status records for the 

FTS_Admin . Get_transf er_inf o call. 

Terms in italics are defined in the ISO File Transfer, Access, and Management protocol, ISO 

8571 FTAM. 



Exceptions 



state_invalid 

The service is in an improper state for a requested operation. 

entity_not_idle 

An entity to be aborted is not idle. 

already_attached 

The ISO transport service is already attached. 

no_t s_attached 

The ISO transport service is not yet attached. 

unknown_entity 

An entity is not registered within the service. 

unknown_account 

An account name is unknown within the service. 

no_ent it y_att ached 

No local entity has been attached to the service. 

string_too_long 

A text parameter exceeded an implementation-defined constraint (see subtype 
identifier t). 
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Declarations 



service_obj_t 



type service_obj_t is limited private; 



service AD t 



type service_AD_t is access service__ob j_t; 
pragma access_kind (service_AD_t, AD); 



entity_obj_t 



type entity obj_t is limited private, 



entity_AD_t 



type entity_AD_t is access entity_ob j_t; 
pragma access_kind(entity_AD_t, AD); 



default_syntax_t 



type default_syntax_t is { 
binary, 
text) ; 



Default syntax for data transfer. 



Enumeration Literals: 

binary Binary data is a sequence of uninterpreted octets. 



text 



Text data is a sequence of characters, with special handling of format ef- 
fectors such as <CR>. 



line t 



subtype line t is System Defs. text (252) 



Used for directory pathnames. 
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short line t 



subtype short_line_t is System_Defs. text (124) ; 

Used for transport addresses, session and presentation selectors. 



identifier t 



subtype identif ier_t is System_Def s. text (28) ; 

Used for titles, remote and local entities, and remote user's names and locations. 



service_params_t 



type service_params_t is 
record 

max_initiator_connections : 
max_direct_connections : 
max_responder_connections : 
timed_requests_of f set : 
low_cost_t ime : 
checkpoint_strategy : 
bulk_data_size : 
buffer_size: 
copy_limit : 
public_directory : 
FTS_directory: 
requeue_af ter_boot : 
timed_queuing_enabled: 
security_attribute_group : 
pr ivate_attribute_group : 
f ile_access_service_class : 
enhanced_f ile_mgt_service_class : 
unconstrained_service_class : 
restart_functional_unit : 
recovery_f unctional_unit : 
re ject_unknown_users : 
re ject_anonymous_users : 
re ject_unauthorized_users: 
timeout_deadline : 
f inished_requests_deadline : 
suspended_deadline : 
def ault_syntax : 
end record; 



System . ordinal ; 

System. ordinal; 

System . ordinal ; 

integer; 

integer; 

integer; 

integer; 

integer; 

integer; 

line_t ; 

line_t ; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

integer; 

integer; 

integer; 

default syntax t, 



for service_params_t use 
record 

max_initiator_connections at range . . 31, 

max_direct_connections at 4 range .. 31, 

max_responder_connections at 8 range . . 31, 

timed_requests_offset at 12 range . . 31, 

low_cost_time at 16 range .. 31, 

checkpoint_strategy at 20 range . . 31, 

bulk_data_size at 24 range . . 31, 

buffer_size at 28 range .. 31, 

copy_limit at 32 range . . 31, 

public_directory at 36 range . . 256*8-1; 

FTS_directory at 292 range . . 256*8-lj 

requeue_after_boot at 548 range . . 7, 

timed_queuing_enabled at 549 range . . 7 

security_attribute_group at 550 range . . 7 
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private_attribute_group 


at 


551 


range 





. 7; 


file access service_class 


at 


552 


range 





. 7; 


enhanced_file_mgt_service_class 


at 


553 


range 





. 7; 


unconstrained_service_class 


at 


554 


range 





. 7; 


restart_functional_unit 


at 


555 


range 





. 7; 


recovery_functional_unit 


at 


556 


range 





. 7; 


reject unknown_users 


at 


557 


range 





. 7; 


re ject_anonymous_users 


at 


558 


range 





. 7; 


re ject_unauthorized_users 


at 


559 


range 





. 7; 


timeout deadline 


at 


560 


range 





. 31 


finished_requests_deadline 


at 


564 


range 





. 31 


suspended deadline 


at 


568 


range 





. 31 


default_syntax 


at 


572 


range 





. 15 


end record; 













Defines parameters for an FTS service. Some parameters may be compared against the im- 
plemented functionality. 

Fields: 

max_initiator_connections 

Maximum number of simultaneously running initiator processes 
(including batched and non-batched processing). The batch daemon will 
not be started if the number of batched connections is zero. 

max_direct_connections 

Maximum number of connections which can be established directly, with- 
out the batcher. 

max_responder_connections 

Maximum number of simultaneously running responder processes. If 
zero, the responder daemon will not be started. 

timed_reguests_off set 

Number of minutes by which the start time of a timed request must exceed 
the current time. 

1 o w_c o s t _t ime 

Hour of the day at which transfer costs are low. 

checkpoint_strategy 

selects the checkpoint strategy: 

No checkpointing. 

1 Checkpoints between data elements. 

2 Checkpoints between data units. 

3 Checkpoint insertion determined by bul k_dat a_ 
size, below. 

bu lk_dat a_s i z e 

Minimum number of bytes before inserting a checkpoint. Only used if 
checkpoint_strategy is 3. 

Size of the protocol data unit (PDU) receive buffer, in bytes. 

Maximum size of copied data elements, in bytes. Data elements which are 
smaller than copy_limit are passed by value (copied) during encoding; 
other (larger) elements are passed by reference. 

public_directory 

The directory, if any, for anonymous or unauthorized users. 



buffer_size 
copy_limit 
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FTS_directory 

Root directory for the FTS directories. 

requeue_after_boot 

If true, connections interrupted by local system crash or reset should be 
requeued. 

timed_queuing_enabled 

If true, timed batch transfer requests may be queued. If false, timed batch 
transfer requests are rejected. 

security_attribute_group 

If true, the security attribute group should be supported. 

private_attribute_group 

If true, the private attribute group should be supported. 

f ile_access_service_class 

If true, the file access service class should be supported 

enhanced_f ile_mgt_service_clas s 

If true, the enhanced file management service class should be supported. 

unconstrained_service_class 

If true, the unconstrained service class should be supported. 

restart_functional_unit 

If true, the restart functional unit should be supported. 

recovery_functional_unit 

If true, the recovery functional unit should be supported 

re ject_unknown_users 

If true, unknown users are not allowed access. If false, unknown users are 
treated like anonymous users. 

re ject_anonymous_user s 

If true, anon users are not allowed access. An accounting object must be 
defined for anonymous users; see FTS_Admin . Def ine_account. 

re ject_unauthorized_users 

If true, remote users who do not provide a filestore password are rejected. 
If false, they are treated as unknown users. 

timeout_deadline 

Default deadline, in seconds, after which timeout will be raised when the 
remote systems keeps quiet. 

finished_requests_deadline 

Deadline, in minutes, when information about finished requests (requests 
which have been completed or rejected) should be removed. 

Information about transfer requests will also be removed if FTS_Tr ans- 
f er . Transf er_inf o is called after transfer completion. 

suspended_deadline 

Deadline, in minutes, after which suspended requests (not timed 
suspended) should be resumed. This parameter affects suspended transfers 
which may have been forgotten. 

default_syntax 

Default syntax to be used for data transfer, either binary or text. 
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entity_params_t 



at 





range 


. 


. 32' 


"8-1; 


at 


32 


range 


. 


. 256*8-1 


at 


288 


range 


. 


. 31 




at 


292 


range 


. 


. 31 




at 


296 


range 


. 


. 31 




at 


300 


range 


. 


. 31 




at 


304 


range 


. 


. 31 





type entity_params_t is 
record 

title: identifier_t; 

ob ject_identif ier : line_t; 

max_in_connections : System. ordinal; 

max_out_connections : System. ordinal; 

tsap_endpoint : System. ordinal; 

session_selector : System. ordinal; 

presentat ion_selector : System . ordinal ; 
end record; 

for entity_j?arams_t use 
record 
title 

ob ject_identif ier 
max_in_connect ions 
max_out_connections 
tsap_endpoint 
session_se lector 
present at ion_selectc 
end record; 

Defines the information necessary to create a local entity. 

Fields: 

title Local entity's title. 

ob ject_identif ier 

Local entity's object identifier. 

max_in_connections 

Maximum number of remotely requested connections allowed through this 
entity. 

max_out_connections 

Maximum number of locally requested connections allowed through this 
entity. 

tsap_endpoint 

Desired transport service access point (TSAP) endpoint (one of the well- 
known endpoints)o The well-known FTS endpoint is 97 c The value 
requests dynamic assignment of the TSAP endpoint (no well-known 
TSAP endpoint available). 

session_selector 

Local entity's session selector. The value means no session selector. 

presentat ion_selector 

Presentation selector. The value means no presentation selector. 
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system_rec_t 



type system_rec_t is 
record 

enabled: boolean; 

defined: boolean; 

title: identifier_t, 

ob ject_identif ier : short_line_t , 
transport_address: short_line_t, 
session_selector : short_line_t, 
presentation_selector : short_line_t , 
alien: boolean; 

timeout_deadline : integer; 
virtual_filename_spec: boolean; 
private_attr : boolean; 

end record; 

for system_rec_t use 
record 

enabled at range . 

defined at 1 range . 

title at 4 range . 

ob ject_identif ier at 36 range . 

transport_address at 164 range . 

session_selector at 292 range . 

presentation_selector at 420 range . 

timeout_deadline at 548 range . 

alien at 552 range . 

virtual_filename_spec at 553 range . 

private_attr at 554 range . 
end record; 



7; 

7; 

32*8-1; 

128*8-1 

128*8-1 

128*8-1 

128*8-1 

31; 

7 

7 

7 



Defines a remote entity. 

Fields: 

enabled If true, this entity definition can be used in addressing a remote entity. 

defined If true, this definition has been explicitly defined with FTS_Admin 

. Register_remote_entity. If false, this definition has been 
created by FTS due to a request from a unknown remote system. 

title FTAM application entity title of the remote entity. 

object_identif ier 

Object identifier of the remote entity. 

transport_address 

Transport service part of the presentation address for the remote entity. 

session_selector 

Session service part of the presentation address for the remote entity. 

presentation_selector 

Presentation service part of the presentation address for the remote entity. 

alien If true, the remote entity resides on an alien (non-BiiN) system. 

timeout_deadline 

Number of minutes to wait after a request before retry or abort. in- 
dicates that the default deadline (servicejparams_t . timeout_ 
deadline) for the service is used. 

virtual_filename_spec 

If true, FTS has to provide the filename in FTAM virtual filestore 
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convention. If false, in the convention of the remote system to the remote 
entity. 

pr i vat e_at t r If true, there is a special use of the private attribute. ( 



status t 



type status_t is 
record 

enabled: 
nr_of_entities : 
nr_of_activities : 
nr_of_connections : 
requests_queued : 
total_number_of_connections : 
total_number_of_local_requests : 
total_number_of_remote_requests: 
re jected_remote_requests : 
recovered_connections : 
aborted_connections : 
number_of_timeouts : 
end record; 



boolean; 
System. ordinal, 
System. ordinal, 
System. ordinal; 
System. ordinal, 
System. ordinal, 
System. ordinal, 
System. ordinal, 
System . ordinal j 
System. ordinal, 
System. ordinal, 
System. ordinal, 



Contains status and statistics information for either an entity or the total service. If a record of 
this type is retrieved for the service the component values are related to the service. If a record 
of this type is retrieved for a specific entity the component values are related to that entity 
only. 



Fields: 

enabled 



If true, either the entity is allowed to accept requests or the service has 
been started. 



nr_of_entities 

For the service, the number of local entities. 

nr_o inactivities 

Current number of activities. 

nr_of_connections 

Number of currently active connections. 

requests queued 

Number of currently queued requests. 

total_number_of_connections 

Total number of connections established since the service was started or 
statistics were reset 

total_number_of_local_requests 

Total number of local connection requests since the service was started or 
statistics were reset 

total_number_of_remote_requests 

Total number of remote connection requests since the service was started 
or statistics were reset. 

re jected_remote_requests 

Number of remote requests which had to be rejected because the max- 
imum number of connections already existed. 

recovered_connections 

Number of connections which have been recovered since the service was 
started or statistics were reset. 
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aborted_connections 

Number of connections which have been aborted since the service was 
started or statistics were reset. 

number_of _t imeout s 

Number of timeouts which have occurred since the service was started or 
statistics were reset. 



activity_description_t 



type act ivity_de script ion_t is 
record 

iriitiating_entity : boolean; 

daemon: boolean; 

state: FTS_Transfer . transfer_state_t; 

remote_entity : identif ier_t ; 

local_entity : identifier_t; 

time : System_Def s . system_time_units; 

activity__id: System, ordinal; 

request_id: System. ordinal; 

recovered: boolean; 
end record; 

Describes an activity (a transfer) within the service. 

Fields: 

initiating_entity 

If true, the activity is handled by an initiating entity. If false, by the 
responding entity. 

daemon If true, this activity is handled by a daemon. 

s t at e Activity's current state. 

remote_entity 

Local name of the involved remote entity. 

lo cal_ent i t y Title of the involved local entity. 

t ime Meaning depends on the activity's state: 

queued Submitting time. 

timed_queued Desired start time. 

suspended Time when the request becomes active. 

timed_suspended 

Resume time. 

requesting Actual start time. 

transferring Actual start time. 

transferred Actual start time. 

terminated Time of completion. 

aborted Time of abortion. 

rejected Time of rejection. 

a c t i vi t y_i d Unique activity identifier for one pair of local and remote entities . 
re que s t_id Internal request identifier, unique within the service. 
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recovered If true, this activity has been recovered. 



activity_descriptions_t ^ 



type activity_descriptions_t is array (positive range <>) of 
activity_description_t ; 

Array of activity description records, used in act ivit ies_t, below. 



activities t 



type activities_t ( 

max_length: integer) is 
record 

length: integer; 

value: activity_descriptions_t (1 . .max_length) ; 
end record; 

List of activities, gotten by FTS_Admin . Get_activity_descriptions or FTS_Ad- 
min . Get_transf er_inf o. 

Fields: 

max_length Maximum number of activities. 

le ngt h Actual number of activities. 

value Array (list) of max_length activity records. 



transfer info list t 



type transfer_info_list_t is array (positive range <>) of 
FTS_Transfer .transfer_info_t; 

Array of transfer information records, used in transfer infos t, below. 



transfer infos t 



type transfer_infos_t ( 
max_length: integer) is 
record 

length: integer; 

value: transfer_info_list__t (1 . .max_length) ; 
end record; 

List of transfer information records, gotten by FTS_Admin . Get_transf er_inf o. 

Fields: 

max_le ngth Maximum number of transfers. 
length Actual number of transfers. 
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value Array (list) of max_length transfer information records. 



identification t 



type identification^ is 
record 

name: identif ier_t; 
location: identif ier_t; 
end record; 

Remote users are identified by their initiator names and locations. 

Remote users' access to the local filestore is controlled through a local account which has a list 
of valid remote user identifications. 

Fields: 

name Initiator name. 

lo cat ion Application title of the remote filestore. 



identification list t 



type identif ication_list_t is array (natural range <>) of 
identification^ ; 

Array of user identification records, used in identif ications_t, below. 



identifications t 



type identif ications_t ( 
max_length: integer) is 
record 

length: integer; 

value: identification_list_t (1 . .max_length) ; 
end record; 

private 

List of remote user/location pairs. Given to FTS_Admin . Def ine_ac count and gotten 
from FTS_Admin . Get_account_inf o. 

Fields: 

max__length Maximum number of identifications. 

length Actual number of identifications. 

value Array (list) of max_length identification records. 
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FTS Transfer 



Provides the procedural interface of the File Transfer Service (FTS), including transfer opera- 
tions. 



Calls 



Abort_transf er 

Aborts a transfer. 

Resume_transfer 

Restarts a suspended transfer. 

Suspend_transfer 

Suspends a batched data transfer either until a Resume__transf er call, or for a 
given duration. 

Transfer 

Initiates a file transfer, returning the transfer ID. 

Transfer_info 

Gets information about a transfer, including the current state of the transfer. 



Summary 

FTS implements the ISO File Transfer, Access, and Management protocol, ISO 8571 
FTAM. Italicized terms are defined in that protocol. 

This package provides operations for: 

• transferring files between the local system and remote systems, 

• suspending and resuming a transfer, 

• aborting a transfer, 

• retrieving transfer status information. 

Transferring a File 

The only information needed for a Transfer call is the local and remote filenames. 

Optionally, you may specify whether the source file is to be removed after the transfer, what to 
do if the destination file exists, the type of processing (synchronous, asynchronous, batch, or 
timed batch), passwords for the remote filestore, whether a log file is used, and an event to be 
signalled upon transfer completion. 

A file transfer may result in the loss of some file attributes, if either the local or the remote 
filestore does not support those attributes. For example, an indexed file may be transferred as 
a sequential file. 
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Types of File Transfers 

There are four ways of processing a transfer request: 

• synchronously within the current job, 

• asynchronously within the current job, 

• in the batch queue, to be executed as soon as possible, 

• in the batch queue, with a given starting time. 

Suspending and Resuming a Transfer 

A transfer in the (timed) batch queue may be suspended by calling Suspend_transf er. 
The suspension may be indefinite (until a Resume_transf er call) or timed. A timed 
suspended transfer is automatically resumed after the given duration. 

A transfer in progress cannot be suspended. 

When a batch or timed batch transfer is suspended, it may be delayed past its scheduled start 
time. If a timed batch transfer is timed suspended, the suspension time is added to the 
transfer's start time. 

Aborting a Transfer 

A transfer can be aborted at any time with Abort_transf er. When a transfer is aborted, 
the associated connection, if any, is closed. A batch transfer that has not been started is 
removed from the queue. 

Aborted transfers cannot be resumed. 

Transfer Information 

The status of a transfer is gotten by calling Tr ansf er_inf o. The status record may be 
retrieved only once for a completed transfer. The status record contains information about the 
transfer, including the last transfer operation, the transfer state, reason for abort if any, direc- 
tion of transfer, local and remote filenames, starting time, and transfer duration. 

For synchronous transfers, non-recoverable errors are indicated by exceptions. For other types 
of transfers, non-recoverable errors are indicated by the abort_reason field with an in- 
cident code corresponding to the exception. 

If logging was enabled for a transfer, detailed information about the transfer is contained in the 
given log file. 



Exceptions 



append_not_supported 

The append operation on an existing destination file is not supported by the remote 
filestore. 

access_control_not_supported 

Attribute access control is not supported by the remote filestore. 

transfer_aborted 

The connection broke and could not be recovered. 

destination_file_already_exists 

The destination file already exists and the file should not be extended or over- 
written (see Transfer parameter if_f ile_exists). 
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destination_file_busy 

The destination file is currently in use and may not be written to concurrently. 

do cument_type_not_appli cable 

The specified document type cannot be associated with the file; the document type 
may be too complex. 

document_type_not_supported 

The required document type is unknown or is not supported by the remote files- 
tore. 

document_type_not_supported_locally 

The required document type is not supported by the local filestore. 

document_type_unknown 

A document type number has been specified for which no document type is 
defined locally. 

illegal_remote_f ilename 

A filename was specified in an incorrect format. For example, it could not be 
divided in filestore and filename components. 

illegal_start_time 

The specified start time has already passed. 

illegal_transfer_id 

A given ID is not a transfer ID. This exception may be raised by every operation, 
and is therefore not mentioned explicitly. 

insuf ficient_functionality 

The remote filestore is not able to read or write a file as requested. 

insuf f icient_j?ermission_on_source 

The user does not have permission to read the source file. If the source file is a 
local file, it may not exist 

insuf f icient_j?ermission_for_delet ion 

The user does not have permission to delete a file, either the destination file prior 
to creation, or the source file after transfer. 

insuf f icient_j?ermission_for_cr eat ion 

The user does not have permission to create the destination file. 

insuff icient_rights 

A given transfer ID does not have the appropriate rights for invoking the opera- 
tion. This may be raised by every operation, hence not mentioned. 

protocol_error 

A protocol error by the remote system has been encountered. 

remote_filestore_keeps_quiet 

The remote filestore did not acknowledge a connection request within a given 
amount of time. 

remote_filestore_unknown 

No information is available about the addressed remote filestore. 

source_file_busy 

The source file is currently in use and may not be read concurrently. 

source_f ile__not_exist 

The source file does not exist 

suspend_re jected 

A requested suspend operation could not be applied successfully to a transfer. 
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transfer_already_suspended 

A given transfer has already been suspended. 

transfer_completed 

A given transfer cannot be suspended because it has already completed. 

transf er_not_suspended 

A transfer to be resumed was not suspended. 

transfer_timed_suspended 

A transfer cannot be directly resumed because it was suspended for a given dura- 
tion. 

transf er_re jected_locally 

A transfer request was rejected by the local system due to resource exhaustion. 

transfer_rejected_remotely 

A transfer request was rejected by the remote filestore without any specific com- 
ment. 

unacceptable_request 

A transfer was requested for two remote files. Only one of the filenames may be a 
remote filename. 

unknown_location 

A location specified in an access control condition is unknown. 

un support ed_parameter_value 

A parameter value is not supported locally. For example, too many conditions for 
access control in Transf er, or a filename is too long. 

user_locally_unacceptable 

The caller is not allowed to use the transfer operation. 

user_remotely_unacceptable 

The caller of the transfer operation (the initiator) is not allowed to access files on 
the remote filestore. 



FTS Transfer-4 



PRELIMINARY 



Declarations 



transfer_object_t 



type transfer__ob ject_t is limited private; 

Represents a transfer. 



transfer id t 



type transfer_id_t is access transfer_ob ject_t , 
pragma access_kind (transfer_id_t , AD) ; 

ID of a transfer. 



info_rights 



info_rights: constant Object_Mgt. right s__mask : = 
Ob ject_Mgt .use_rights; 

Required to get information about the status of a transfer (Transfer info call). 



control_rights 



control_rights : constant Ob ject_Mgt .rights_mask := 
Ob ject_Mgt . control_rights; 

Required to invoke an operation concerning the transfer (Suspend_transf er, Resume 
transfer, and Abort transfer calls). 



access set t 



type access_set_t is ( 
read, 
write, 

read_attributes, 
delete, 
create) ; 

Enumerates the possible actions on a file during a file transfer. 

Enumeration Literals: 

read Read the file. 

write Write the file. 

read_attributes 

Read the file's attributes. 
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de let e Delete the file, 

create Create the file. 



access t 



type access_t is array (access_set_t) of boolean; 

Array of access conditions. A true element indicates that the associated (indexing) access 
operation is allowed. See also type access_passwords_t. 



identifier t 



subtype identif ier_t is System_Def s. text (28) ; 

Container for short texts, such as passwords, object identifiers, and titles. 



null identifier 



null_identif ier : constant identifier_t := ( 
28, 0, (others => ' ')) ; 

Null or default identifier. 



line t 



subtype line_t is System_Defs .text (252) ; 

Container for long texts, such as local and remote filenames. 



access_passwords_t 



type access__passwords_t is array (access_set_t) of identif ier_t; 

Array of access passwords. Each element is a password which may be necessary for the 
corresponding access. 



condition t 



type condition_t is 
record 

action_list: access_t := (others => false); 

identity: identif ier_t := null_identif ier; 

passwords: accessj>asswords_t := (others => null_identifier) ; 

location: identif ier_t := null_identif ier; 
end record; 
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File access condition record. Each of the four components must be satisfied to fulfill the 
condition. 

Fields: 

action_list Types of access which are allowed by this access condition. 

ident it y Accessor identity to be matched, if any. 

pa s s wo r ds Passwords to be matched, if any, for each allowed type of access, 

location Accessor location (filestore name) to be matched, if any. 



condition_array_t 



type condition_array_t is array (natural range <>) of condition_t, 

Array of access condition records, used in access_control_t, below. 



access control t 



type access_control_t ( 
maxnr: natural) is 
record 

actlen: natural; 

value: condition_array_t (1 . .maxnr) ; 
end record; 

Array of access control conditions under which access to a file is allowed. Access to a file is 
allowed if at least one of these conditions (which in turn consist of four terms, all of which 
have to be matched) is satisfied. 

Fields: 

maxnr Maximum number of access control conditions. 

actlen Number of valid access control conditions in value array. 

value Array of maxnr access control conditions. 



default access control 



default_access_control: access_control_t (0) :=( 
0, 0, (others => ( 

(others=>false) , 

null_identifier, 

(others => null_identifier) , 

null_identif ier) ) ) ; 

Default (null) access control value. 
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MAX CONDITIONS 



MAX_CONDITIONS: constant integer := 4; ^ 

Maximum number of conditions which can be specified with a Transfer call. 



document_type_t 



subtype document_type_t is integer range 0..127; 

A document type describes the file model and the file contents in a standardized manner, hence 
allowing the file characteristics to be maintained in the remote filestore. 

Some document types are predefined by FT AM, others will be defined successively by stan- 
dardization organisations. Therefore, the following list may be extended in later versions of 
this package. Other values may be used when they are implemented in FTS. 



FTAM 1 



FTAM_1 : constant document_type_t := 1, 

Unstructured text file. 



FTAM 2 



FTAM_2 : constant document_type_t := 2, 

Sequential text file. 



FTAM 3 



FTAM_3 : constant document_type_t := 3; 

I 



Unstructured binary file. 



FTAM 4 



FTAM_4 : constant document_type_t := 4; 

Sequential binary file. 
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processing_t 



type processing_t is ( 
synchronous, 
asynchronous, 
batch, 
timed_batch) ; 

Possible modes of file transfer processing. 

Enumeration Literals: 

synchr oriou s A Transfer call returns only after the transfer is complete or aborted. 

asynchronous A Transfer call executes concurrently. 

batch A transfer request is put into the batch queue. 

timed_batch A transfer request is put into the batch queue for execution at a specified 
time. 



if file exists t 



type if_f ile_exists_t is ( 
error, 
overwrite, 
append) ; 

Action to be taken when the destination file already exists. 

Enumeration Literals: 

error An error will be signaled. 

overwr it e The existing destination file will be overwritten. 

append The new data will be appended to the existing file. 



duration t 



type duration_t is 

record 

hours: System. byte_ordinal range .. 255, 
minutes: System. byte_ordinal range .. 59; 
seconds: System. byte_ordinal range .. 59; 

end record; 



An amount of time, used for timed suspensions and for timing transfers. 



Fields: 

hours 

minutes 

seconds 



Number of hours. 
Number of minutes. 
Number of seconds. 
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time t 



type time_t is 
record 
month: 
day: 
hour: 
minute : 
second: 



System.byte_ordinal range 0..12; 
System. byte__ordinal range 0..31; 
System. byte_ordinal range 0..23; 
System. byte_ordinal range 0..59; 
System. byte ordinal range 0..59; 



relative_time: boolean; 
end record; 

Describes a time (such as the start time of batch request), either relative to the current time or 
absolute. 



Fields: 

month 
day 

hour 
minute 
second 
relative time 



Number of month (January = 1, ..., December = 12). 

Day of the month. 

Day indicates that no start time has been specified. 

Hour of the day, in 24-hour format. 

Minute of the hour. 

Second of the minute. 

If true, the specified time is relative to the time when the request was 
invoked. If false, the specified time is absolute. 



no start time 



no_start_time: constant time_t : = {0,0, 0, 0, 0, false) ; 

Null or default start time. 



operationj 



type operation_t is ( 
Transfer, 
Suspend_transfer, 
Resume_transfer, 
Abort_tr ansf er , 
Transfer_state) ; 

Enumerates the possible transfer operations. Used in the transfer information record (see 
transfer_info_t). 

Enumeration Literals: 

Transfer The last operation was a Transfer call. 

Suspend__transfer 

The last operation was a Suspend_transf er call. 
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Resume_transfer 

The last operation was a Resume__transf er call. 



Abort transfer 



The last operation was a Abort_transf er call. 



Transfer state 



The last operation was a Transf er_inf o call. 



transfer state t 



type transf er_state_t is ( 
queued, 
timed_queued, 
suspended, 
timed_suspended, 
requesting, 
transferring, 
transferred, 
terminated, 
rejected, 
aborted) ; 

Enumerates the possible states of a transfer. Used in the transfer information record (see 

transf er_info__t). 

Enumeration Literals: 

queued The transfer is in the batch queue. 

t imed_queued The transfer is in the timed batch queue. 

suspended The transfer has been suspended. 

timed_suspended 

The transfer has been suspended for a given duration. 

requesting Connection requests are due to be issued. 

transferring The transfer is in progress. 

transferred The file has been completely transferred. 

terminated The connection has been terminated after a successful transfer. 

rejected The transfer request has been rejected. 

aborted The transfer and the connection have been aborted. 



transfer info t 



type transfer_info_t is 
record 

last_operation : 

state: 

abort_reason : 

diagnostic: 

processing: 

attr ibutes_altered : 

f ilename_truncated : 

remote_to_local : 

remote_f ilestore : 

remote_f ile : 

local file: 



operation_t; 

transf er_state_t; 

Incident_Defs . incident_code, 

System. short_ordinal; 

processing_t; 

boolean; 

boolean; 

boolean; 

identifier_t; 

line_t; 

line t; 
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access_control : access_control_t (MAX_CONDITIONS) ; 

erase_source : boolean; 

if_f ile_exists : if_f ile_exists_t; 
destination_file_existed: boolean; 

document_type : document_type_t; 
document_type_simplif ied: boolean; 

access_passwords : access_passwords_t; 

logging_enabled: boolean; 

logfile: line_t; 

start_tlme: time_t; 

transferred_bytes: integer; 

transfer_time: duration_t; 
' end record; 

Transfer information record gotten by Trans f er_inf o. 

Fields: 

last_operation 

Last operation which has been performed for this transfer request. 

s t at e Transfer state. 

abor t_reas on Reason for a transfer being aborted, for asynchronous, batched, and timed 
batch transfers. 

di agno s t i c Last diagnostic code according to FT AM Diagnostic Definitions (Part III). 

proces sing Processing mode for this transfer. 

attributes_altered 

If true, the attributes of the destination file have been altered due to files- 
tore restrictions. 

filename_truncated 

If true, the remote filename has been truncated by the remote filestore due 
to restrictions on filename length. 

remote_to_local 

If true, the transfer request is from remote to local filestores. If false, the 
transfer is from local to remote filestores. 

remote_f ilestore 

Remote filestore's name. 

remote_f ile Remote file's name. May have been truncated (when f ilename_ 
truncated is true). 

local_file Local file's pathname. 

access_control 

Access control conditions for this transfer request If the Tr an s f er 
call's dest_access_control parameter was specified, contains the 
actually requested access controls. 

Values will be contained in this record only if the transfer ID given to the 
Transf er_inf o operation has control rights. 

er ase_sour ce If true, the source file is to be erased after the transfer (a file move). 

if_f ile_exists 

Action to be taken if the destination file exists. 

destination_f ile_existed 

If true, the creation of a new file caused the deletion of a previously exist- 
ing file. 
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do cume nt_t ype 

Actual document type name/number. 

document_type_simplified 

If true, the original document type was unacceptable to the destination 
filestore and had to be simplified. 

access_pas swords 

Access control passwords for this transfer request. 

Values will be contained in this record only if the transfer ID given to the 
Transf er_inf o operation has control rights. 

logging_enabled 

If true, transfer logging is performed. 

logfile Transfer log file's pathname. Only valid if logging_enabled is true. 

s t ar t_t ime Actual transfer start time. 

transf erred_bytes 

Number of bytes successfully transferred. 

transfer_time 

Total amount of time needed for the file transfer. 



transfer info VA t 



type trans fer_info_VA_t is access transf er_info_t; 
pragma access_kind (transfer_info_VA_t, virtual) ; 

Virtual address of a transfer information record. 
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Abort transfer 



procedure Abort_transf er ( 

transfer id: transfer id t) ; 



Parameters 

transfer id ID of transfer to be aborted. 



Operation 

Aborts a transfer. 



A transfer cannot be resumed after it has been aborted. If a transfer is still in the batch queue, 
the transfer request is removed from the queue. Even a suspended transfer can be aborted. 



Exceptions 



transf er_aborted 

The transfer was already aborted. 

transf er_completed 

The transfer was already completed. 
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Resume transfer 



procedure Resume_transfer ( 

transf er_id: transf er_id_t; 
restart: boolean := false); 



Parameters 

transfer_id 
restart 



ID of suspended transfer to be resumed. 

Optional. If true, the transfer should be restarted at the beginning of the 
file. If false (default), the transfer is continued at the last acknowledged 
checkpoint. 



Operation 



Restarts a suspended transfer. 



Exceptions 



insuf f icient_rights 

remote_f ilestore_unknown 

remote_f ilestore_keeps_quiet 

transf er_aborted 

transf er_not_suspended 

transfer_timed_suspended 

A timed_suspended transfer cannot be resumed; it will be automatically 
resumed after the given delay. 

transf er_completed 



?i»T 
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Suspend Jransfer 



procedure Suspend_transf er ( 

transfer_id: transfer__id_t; 
timed_resume : boolean := false; 
suspension_time: duration_t := (0,1,0) ); 

Parameters 

transfer_id ID of transfer to be suspended. 

t imed_r e sume Optional. If true, the transfer is to be resumed automatically after 

su spen s i on_t ime has expired. If false (default) the user has to restart 
the transfer explicitly with a Resume_transf er call. 

suspension_time 

Optional. Duration after which the suspended transfer is automatically 
continued. The default suspension time is one minute. 

Ignored if t ime d_r e s ume is false. 

Operation 

Suspends a batched data transfer either until a Re sume_t rans f er call, or for a given dura- 
, s tion. 

j ( y i :■:,. Suspending a batch transfer affects its start time. 

Exceptions 

transfer_aborted 

transf er_already_suspended 

transfer_completed 

: insuff icient__rights 

suspend_re jected 

The local FTS has determined that the transfer cannot be suspended. 
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Transfer 



function Transfer ( 
source_file: 
destination_f ile : 
document_type : 
dest_access_control : 
erase_source : 
if_f ile_exists : 
processing: 
start_time : 
access_passwords : 
f ilestore_password: 
remote_account : 
logging_enabled: 
logf ile : 

terminate_action : 
return transfer id t; 



System_Def s . text ; 

System_Def s . text ; 

document_type_t := 0; 

access_control_t := default_access_control; 

boolean := false; 

if_f ile_exists_t := error; '■>-?;■;/'.'•, f- '"•'* 

processing_t := asynchronous; " ' 

time_t := no_start_time; 

access j>asswords_t := (others => null_identifier) 

identifier_t := null_identif ier; 

identifier_t := null_identif ier; 

boolean := false; 

System_Def s . text := System_Def s . null_text; 

Event_Mgt . action record := Event Mgt.null action) 



Parameters 



source_f ile Source file's pathname. 

destination_f ile '-oltBVz^tO 

Destination file's pathname. 

do cument_t ype 

Optional. Document type to be associated with the file and used for the 
transfer. A value of (default) indicates the unknown document type. 

dest_access_control 

Optional. If the source file is created, specifies access conditions for the 
newly created file. Default is no restrictions. 

erase_sour ce Optional. If true, the source file is erased after the transfer (a file move). 
If false (default), the source file is not erased (a file copy). 

if_f ile_exists 

Optional. Action to be taken if the destination file already exists. Possible 
values are error, overwrite, and append. 

processing Optional. Type of data transfer, either synchronous, 
asynchronous, batch, or timed_batch. 

start_time Optional. Transfer starting time for timed batch requests. Ifno_start_ 
time (default), FTS uses the service's default low_cost_transf er_ 
time. 

Ignored if processing is not timed_batch. 

access^ pas swords 

Optional. Set of access passwords which may be necessary for the remote 
filestore to permit operation. 

filestore_password 

Optional. Remote login's password. 

remote_account 

Optional. Remote account name. The default is the caller's login name. 

logging_enabled 

Optional. If true, detailed transfer information is written to a log file. 

logf ile Optional. Log file's pathname. If System_Def s . null_text 

(default), standard output is used. 
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Ignored if logging_enabled is false. 

terminate_action 

Optional. Action to be signalled on transfer termination. {. 

Ignored if processing is synchronous, batch, ortimed_batch. 

Return Type and Value 

transfer_id_t 

Transfer request ID. 

Operation 

Initiates a file transfer, returning the transfer ID. 

The caller defines the transfer direction by specifying the remote filename either as the source 
or as the destination. 

The transfer ID is used for subsequent operations (such as Suspend__transf er). 

The local filename is specified as usual (for example, / my_di r / 1 o c a l_f i 1 e). The remote 
filename must be of the form /FTS I ' remote_$ystem_name I remote Jilename. 

For synchronous transfers (processing «> synchronous), all errors are reported by 
exceptions. In the other types of processing, errors concerning parameters are reported by 
exceptions. For asynchronous and batch transfers, errors occuring during the transfer are only 
reported in the transf er_inf o_t . abort_reason field. 

If logging is enabled (logging_enabled => t rue), error messages and information 
about the transfer are written to the given log file (default is standard output). The error 
messages are similar to the exception names and may be more detailed. 

The caller may request to be notified by an event (terminate_act ion) about normal or 
abnormal completion of an non-synchronous transfer. If synchronous processing is requested, 
any action record is ignored. 

FTAM introduced document types to describe classes of files and file contents (see subtype 
document = type_t). Several document types have been defined, and new document types 
may be defined later. Not all of the defined document types are supported by FTS. If no 
document type is specified (do cument_type -> 0), FTS chooses the actual document 
type of the file which is to be transferred; otherwise, the given document type is used. The 
specified document type must be either the same as the actual document type of the file, or a 
simplification; otherwise the exception document_type_not_applicable is raised. 
The document type actually used can be found in the transfer information record. 

Exceptions 

access_control_not_supported 

append_not_supported 

destination_file_already_exists 

destination_file_busy 

do cume nt_t ype_no t_appl i c ab le 
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document_type_not_supported 

document_type_not_supported_locally . 7 

document _type_unknown 

illegal_remote_f ilename 

illegal_start_time 

insuff icient_jpermission_on_source "'"*' '**^ . lUJJrt 

insuf f icient_j?ermission_for_deletion 

insuf f icient_permission_for_creation 

insuf ficient_functionality ^^ItrTlSoO 

protocol error . . ,. 

remote_f ilestore_keeps_quiet 

remote_f ilestore_unknown •.-;:,;:..- 

source_f ile_busy 

source_file_not_exist m- >.,■:< -; r r^runi sdT 

transfer_aborted '■■--»' 3riT 

transf er_re jected_locally ' ; T;in&lli 

An asynchronous transfer cannot be performed due to a restricted number of direct 

requests. 

transf er_rejected_remotely ' ^ 

unknown_location _ ... 

unsupported__parameter__value 

unacceptable_request 

Two remote or two local filenames were specified. 

user_locally_unacceptable 

user_remotely_unacceptable * ' 5?il 

■ .: :■•■ ..*;.; '•<>;. :n 

j." ,,T 'OOqvl 



enollas: 
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Transfer info 



procedure Transf er_info( ^ 

transf er_info_VA: transfer_info_VA_t; 
transfer_id: transfer_id_t) ; 

Parameters 

t r an s f e r__i nf o_VA 

Virtual address of a transfer information record which receives the infor- 
mation. 

transf er_id ID of transfer for which information is retrieved. 

Operation 

Gets information about a transfer, including the current state of the transfer. 

If the transfer has been completed (perhaps unsuccessfully), the transfer information can only v 
be retrieved once. 



Exceptions 



transf er_completed 

The transfer information record has already been retrieved. 
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